免费开源AI软件.桌面单机版，可移动的AI知识库，察元 AI桌面版

察元 AI · 桌面单机版免费开源的知识库

离线优先 · 国产系统适配 · 全栈本地知识库 · 多模型对抗

一句话定位

察元 AI 桌面单机版 是一款装到电脑里就能用、不联外网也能跑 的 AI 助手 ------

内置多供应商大模型网关 · 文档/结构化/向量/办公/外部库五类知识源 · 30+ 内置工具 · MCP 协议 · 模型对抗 ,

原生适配 Windows / macOS / Linux / 麒麟 / 统信 UOS / openKylin 等系统;

所有数据落到用户自选目录,密钥与文档永不出域,真正的"自有 AI"。

一、版权声明与开源许可(AGPL-3.0)
二、品牌标识保留要求
[三、与 chayuan-wps WPS 加载项的关系](#三、与 chayuan-wps WPS 加载项的关系)
四、产品概述与系统架构
五、核心特性
六、支持的操作系统
[七、与豆包 / Cherry Studio 等的 60+ 项细致对比](#七、与豆包 / Cherry Studio 等的 60+ 项细致对比)
八、详细功能清单
- [8.1 对话与流式](#8.1 对话与流式)
- [8.2 知识库类型与文档格式](#8.2 知识库类型与文档格式)
- [8.3 数据库连接器(结构化数据)](#8.3 数据库连接器(结构化数据))
- [8.4 向量库支持](#8.4 向量库支持)
- [8.5 模型供应商](#8.5 模型供应商)
- [8.6 嵌入模型 / 重排 / OCR](#8.6 嵌入模型 / 重排 / OCR)
- [8.7 多模态](#8.7 多模态)
- [8.8 内置工具(30+)](#8.8 内置工具(30+))
- [8.9 MCP(Model Context Protocol)](#8.9 MCP(Model Context Protocol))
- [8.10 模型对抗(Model Arena)](#8.10 模型对抗(Model Arena))
- [8.11 自动构建文档知识结构(Folder Sync)](#8.11 自动构建文档知识结构(Folder Sync))
- [8.12 引用展示与原文回链](#8.12 引用展示与原文回链)
[九、HTTP API 接口总览](#九、HTTP API 接口总览)
十、开发者搭建指南
十一、使用教程入口
[十二、安全 · 隐私 · 离线](#十二、安全 · 隐私 · 离线)
十三、路线图
[十四、社区 / 反馈 / 商业合作](#十四、社区 / 反馈 / 商业合作)
十五、致谢与第三方组件
附录甲:常见问题(FAQ)
附录乙:术语表

一、版权声明与开源许可

软件名称

中文全称: 察元 AI · 桌面单机版
英文名: Chayuan AI · Desktop (Single-Machine Edition)
包名 / 二进制名: chayuan-desktop
出品方: 北京智灵鸟科技中心

开源许可:AGPL-3.0

本仓库源代码依照 GNU Affero General Public License v3.0 授权。

AGPL-3.0 与 Apache-2.0 / MIT 的关键区别在于 网络传播条款(§13) :

一旦您把基于本软件构建的版本通过网络对外部用户 提供服务(SaaS / 私有云 / 公网部署),

您必须以相同的 AGPL-3.0 许可向这些用户提供完整的对应源代码 (包括您自己的修改)。

仅在单位内部、内网部署、本机使用 这一类 "不构成公开网络传播" 的形态下,

您可以保留对源代码的封闭修改。

这意味着:

✅ 个人 / 团队 / 企业内部部署、内网使用、本地修改:自由,无任何商业限制
✅ 二次开发后再分发安装包(保留 AGPL 与版权声明):允许
⚠ 把修改后的版本部署成 SaaS / 公网服务 提供给外部用户:必须开源您的修改
⚠ 集成到您的闭源商业产品中并对外销售:需先取得单独的商业许可

著作权与免责

产品由 北京智灵鸟科技中心 研发与运营,涉及的界面文案、默认提示词、图标、品牌素材等

除第三方组件按其各自许可外,均受著作权与相关知识产权法保护。

免责声明(摘要): 本软件按 "原样" 提供;大模型生成内容可能存在不准确或不适用情形,

涉密、合规与法律判断应以人工与正式制度为准;任何检查类辅助功能(保密检查、AI 痕迹检查等)
仅作辅助参考,不构成司法鉴定或保密定密结论。

二、品牌标识保留要求

为保证用户知情权、来源可追溯性与品牌一致性,面向最终用户的界面中 ,以下位置出现的
"察元" 及其固定搭配的产品称谓(包括但不限于 "察元 AI"、"察元 AI 助手"、"察元智库"、

"察元对抗"、"关于察元" 等)属于产品来源与品牌标识的重要组成部分:

应用窗口标题、Splash、关于页、设置 → 关于
系统托盘图标提示、桌面快捷方式名称(默认 察元AI.lnk)
帮助中心 / 反馈弹窗中的固定品牌表述
与上述同语义链路的用户可见字符串

未经权利人书面授权,任何再分发或定制版本不得对上述位置的"察元"相关固定文案进行
替换、删减、遮挡、淡化或误导性改写(例如改为其他商业名称却仍指向本软件,使用户误认为来源已变更)。

此约束不构成 对 AGPL-3.0 所允许之 "修改源代码" 本身的禁止 ------ 您仍可在内部构建中调整代码逻辑;

但若您向第三方提供可安装的、面向最终用户的构建产物 ,需保留品牌标识的显著性,

或事先取得权利人书面同意按约定方式标注来源。白标 / 整体本地化 涉及品牌字段调整,

请通过商务渠道获取单独授权条款。

三、与 chayuan-wps WPS 加载项的关系

察元 AI 是一个端到端办公 AI 平台,目前由两个互补的开源项目共同覆盖:

项目	仓库	形态	主要用户
chayuan-desktop(本仓库)	https://github.com/zhgyuhuii/chayuan-desktop.git	桌面单机应用 ------ Tauri 2 外壳 + 嵌入式 Python 后端	不愿暴露密钥/文档到外网的个人、政企单机用户
chayuan-wps	https://github.com/zhgyuhuii/chayuan.git	WPS 文字加载项 ------ Vue 3 加载项,运行在 WPS 内部	重度使用 WPS 编辑公文 / 合同 / 标书的政企作者

二者如何协作

复制代码

                ┌────────────────────────────────────────────┐
                │   察元 AI 桌面单机版 (chayuan-desktop)      │
                │   ─────────────────────                    │
                │   • 嵌入式 chayuan-server(Python)         │
                │   • 知识库 / 模型网关 / 工具 / MCP          │
                │   • 监听 127.0.0.1:62581                   │
                │   • 数据落用户目录 (CHAYUAN_ROOT)          │
                └─────────────────┬──────────────────────────┘
                                  │  HTTP/REST(同机或内网)
                                  │  /api/v1/kb-query/search
                                  │  /api/chat/completions
                                  │  /openapi/v1/*  (HMAC 签名)
                                  ▼
                ┌────────────────────────────────────────────┐
                │   chayuan-wps  (WPS 加载项, Vue 3 + Vite)   │
                │   ─────────────────────                    │
                │   • 运行在 WPS 文字内,任务窗格 + Ribbon    │
                │   • 选区/全文上下文感知                     │
                │   • 写回链路:插入/替换/批注/链接批注       │
                │   • 调用桌面单机版的 /api/* 拿模型与知识    │
                └────────────────────────────────────────────┘

典型用法 :用户在公司电脑上装好 chayuan-desktop ,作为本机 "AI 服务器",

后端 sidecar 起在 127.0.0.1:62581;再在 WPS 里安装 chayuan-wps 加载项,

加载项的 "服务器地址" 配置成 http://127.0.0.1:62581,两边共用同一份知识库、
同一套模型配置、同一份对话历史 ------ 在 WPS 里发起的对话也会出现在桌面客户端的历史里。

现状

当前 chayuan-wps v3.0 已落地远程知识库 RAG 集成(JWT 用户态 + HMAC 应用态),
完整支持把 chayuan-desktop 当作后端使用。
桌面单机版默认 关闭鉴权 (单机用户没有用户的概念),WPS 加载项侧已加 authMode: 'none'
分支,可以无密钥直连本机后端。

详见 chayuan-wps 仓库的 README 与 RELEASE_NOTES_v3.0。

四、产品概述与系统架构

4.1 它是什么

察元 AI 桌面单机版 把一个完整的"企业级 AI 后端"塞进了你的电脑里 ------ 安装包打开就能用,

不需要 Docker、不需要单独装 Python、不需要起 Redis / RabbitMQ / Postgres。所有重活

(语言模型调用、知识库索引、向量检索、工具执行、流式编排)都在本机进程里完成,

前端是一个原生窗口的 React 应用,后端是一个嵌入到安装包里的 Python sidecar。

4.2 三层架构

复制代码

┌──────────────────────────────────────────────────────────────────────┐
│  Frontend  Tauri 2 + React 19 + Tailwind                              │
│  ───────────────────────────────────────────────────                  │
│  • 多 Tab 浏览器式外壳(主页 / 聊天 / 知识库 / 模型广场 / MCP / 工具)  │
│  • 多泳道模型对抗 (Model Arena)                                       │
│  • 折叠式工具调用展示 / 引用面板 / 流式 reasoning                     │
│  • 本地 SQLite 持久化对话(Tauri sql 插件)                          │
│  • Stronghold 凭据保险箱(ChaCha20-Poly1305 + Argon2id)             │
└──────────────────────────┬───────────────────────────────────────────┘
                           │  spawn + /healthz 探活
                           ▼
┌──────────────────────────────────────────────────────────────────────┐
│  Sidecar  chayuan-server (Python 3.12, FastAPI)                       │
│  ───────────────────────────────────────────────────                  │
│  • 单机 profile:无 Redis / 无 Celery / 无 PostgreSQL                  │
│  • 向量库:sqlite-vec (内嵌 SQLite 扩展) / 可选 FAISS                 │
│  • 缓存:cachetools TTLCache / 队列:asyncio.Queue                    │
│  • 嵌入模型:ONNX 本地(默认 bge-m3-onnx)/ Ollama / OpenAI 兼容     │
│  • OCR:RapidOCR-ONNX(纯 CPU,~70 MB)                              │
└──────────────────────────┬───────────────────────────────────────────┘
                           │  HTTP / OpenAI 兼容
                           ▼
┌──────────────────────────────────────────────────────────────────────┐
│  External  用户自选的模型与知识源                                     │
│  ───────────────────────────────────────────────────                  │
│  • 本地推理:Ollama / LM Studio / vLLM / Xinference                  │
│  • 云端 LLM:OpenAI / DeepSeek / 通义千问 / 智谱 / 文心 / Moonshot...  │
│  • 业务数据库:MySQL / PostgreSQL / Oracle / 达梦 / 金仓 / Doris...    │
│  • 外部向量:Milvus / Chroma / Elasticsearch / Zilliz                │
└──────────────────────────────────────────────────────────────────────┘

4.3 启动时序

用户双击 察元AI 桌面图标
Tauri 主窗口(window.backgroundColor = #0f172a)瞬间出现,首屏即有炫酷 splash 动画
(五层零延迟挂载:OS 窗口背景 → HTML inline CSS → splash 节点 → JS 自检注入 → React 接管时同步淡出)
Tauri 主进程 spawn 嵌入的 chayuan-server 子进程,通过 CHAYUAN_ROOT=<用户首启动选定的目录>
注入数据路径
前端 SidecarGate 轮询 /healthz,后端就绪后渲染主界面
首次启动用户自选 "数据目录"(默认平台标准目录),后续启动直接复用

五、核心特性

5.1 离线优先(Offline-First)

嵌入式后端:Python 解释器 + 全部 wheels + sqlite-vec 扩展 + 资源文件全部进安装包,装机即可离线启动
嵌入式模型:默认带 ONNX 量化的 bge-m3 嵌入模型(~120 MB),不需要外网下载
嵌入式 OCR:RapidOCR-ONNX 模型权重 bundle 进 sidecar,文档解析全本地
可选本地 LLM:与 Ollama / LM Studio / vLLM / Xinference 一键对接,大模型推理也能完全断网
离线 Doctor 命令:自检数据目录、sqlite-vec 扩展、嵌入模型完整性

5.2 察元智库(Knowledge Universe)

统一查询路径 ------ 把文档、结构化数据库、外部向量库、办公私库、图像库五类知识源

抽象为 ku_id (Knowledge-Universe ID),前端选什么类型的源,服务端自动路由到对应的检索 adapter。

POST /api/v1/kb-query/search 一个端点搞定多源混合检索
五类源:
- doc:<kb_name> 文档知识库(PDF / Word / Excel / Markdown / HTML / 图像 ...)
- src:<source_id> 结构化数据源(SQL / MongoDB / Elasticsearch)
- vec:<collection> 外部向量库(Milvus / Chroma / Zilliz)
- office:<owner>[:<group>] 办公私库(企业 / 团队 / 个人三层)
- img:<kb_name> 图像知识库(CLIP 嵌入)
统一返回 RetrievalChunk + Citation,带原文回链 / 信任度 / 生成的 SQL DSL / collection / vector id
混合检索:向量 + BM25 关键词同跑,加权打分
重排:可选 BAAI/bge-reranker-v2-m3 等 cross-encoder
诊断 :每次查询返回 Diagnostic[],排查 "答非所问" 时一目了然

5.3 察元 AI 对话(Chayuan Chat)

多 Tab 浏览器式外壳:像浏览器一样打开多个对话,每个 Tab 独立持有 conversationId / 模型 / KB 选择
流式 markdown 渲染:Shiki 代码高亮 + reasoning(深度思考)token 折叠展示
工具调用三层折叠 :
- 第一层:摘要 chip(图标 + 工具名 + "已调用 N 次")
- 第二层:展开看 args / output 摘要
- 第三层:再点开看完整 JSON
引用面板:KB 来源列表 + 信任度星级 + 一键打开原文 / 下载附件
附件上传:拖拽 / 粘贴 / 点击,自动 OCR 入库后参与对话上下文
对话本地持久化:Tauri SQLite 插件,删账号也不丢历史

5.4 多模型对抗(Model Arena)

一个对话页面最多 N 个泳道(无上限),每个泳道独立选模型
统一发送:打勾后,在任何一道输入,会同时发到所有泳道,横向对比生成质量
泳道操作:折叠 / 调宽 / 拖动重排 / 添加 / 删除
折叠条标题 :自动取该泳道的首条用户提问作为竖向标签(如 "你是谁"),不是模型名

5.5 模型广场(Model Marketplace)

7 个分类标签:推荐 / 全部 / 本地 / 国内 / 国外 / 聚合 / 自定义
厂商卡片网格:logo + 名称 + 标签 + 启用开关 + 设置齿轮
自动拉取模型清单 :填了 API Key 失焦自动调供应商 /v1/models 拉模型并归类
默认模型自动落候选:模型广场配好后,如果设置页没设默认模型,自动按类别提升候选第一个为默认
模型类型分类:对话 / 嵌入 / 图像生成 / 视觉理解 / 重排 / 语音合成 / 语音识别 / 视频

5.6 本地 OS 适配 + 国产化

详见六、支持的操作系统。

六、支持的操作系统

类别	系统	架构	状态
Windows	Windows 10 (1809+) / Windows 11	x86_64	✅ 完整支持(NSIS 安装包 + WebView2 自动安装)
macOS	macOS 11 (Big Sur) 及更高	Apple Silicon (arm64) / Intel (x86_64)	✅ 完整支持(.dmg + 公证就绪)
Linux	Ubuntu 22.04+ / Debian 12+	x86_64 / aarch64	✅ 完整支持(.deb / .rpm / .AppImage)
国产 Linux	麒麟 V10(Kylin V10)	x86_64 / aarch64 / 龙芯 LoongArch64	✅ 兼容(基于 Ubuntu/Debian 共享 webkit2gtk)
国产 Linux	统信 UOS(UnionTech OS)	x86_64 / aarch64	✅ 兼容
国产 Linux	openKylin(开放麒麟)	x86_64 / aarch64	✅ 兼容
国产 Linux	deepin	x86_64	✅ 兼容
国产 Linux	银河麒麟服务器版	x86_64 / aarch64	⚠ 需手动装 webkit2gtk-4.1
国产 Linux	欧拉 openEuler	x86_64 / aarch64	⚠ 需 RPM 包(包含在 build 矩阵)
CPU 架构	x86_64 / aarch64 (arm64) / loongarch64	---	✅ 三种架构均有发版

国产化对接说明

签名工具:支持中国 SM2/SM3/SM4 算法的代码签名(规划中,详见路线图)
国产数据库 :已对接 达梦 DM 、人大金仓 KingbaseES 、Apache Doris ------ 详见 §8.3
国产模型 :已对接 DeepSeek 、通义千问 (Qwen) 、智谱 GLM 、文心一言 、Moonshot Kimi 、
豆包 (Doubao) 、SiliconFlow 、百川、MiniMax ------ 详见 §8.5
国产 OCR:RapidOCR-ONNX(原 PaddleOCR 模型转 ONNX,纯 CPU 即可跑)
国产嵌入:智源 BAAI/bge-m3-onnx(默认嵌入模型)、bge-reranker-v2-m3(默认重排)

七、与豆包 / Cherry Studio 等的 60+ 项细致对比

以下对比基于 2026-05 各家产品常见公开形态 做归纳,仅作选型参考,不构成 对任何第三方的功能承诺或排名。

计费、数据驻留、企业私有化、监管认证等以各厂商官方文档与合同为准。

7.1 具名概要对照(横向)

对比项	察元 AI 桌面单机版	豆包 (Doubao) 桌面	Cherry Studio	ChatGPT Desktop	LM Studio	Open WebUI	AnythingLLM	Chatbox
形态	Tauri 桌面 + 嵌入式 Python 后端,全栈本地	字节 Doubao 客户端(对接字节云)	Electron 多供应商客户端	OpenAI 官方桌面(走 OpenAI 云)	Electron 本地推理工作台	Web UI(配合 Ollama 等本地推理)	Electron + Node 后端	Tauri 跨平台对话客户端
后端形态	嵌入式 Python sidecar(单机包)	字节云	各家 API 中转	OpenAI 云	本机 llama.cpp	独立 Web 服务	Node + 嵌入式向量库	客户端直连厂商 API
离线 LLM	✅ Ollama / LM Studio / vLLM / Xinference 一键对接	❌ 必须联网	✅ 部分支持	❌	✅ 主打离线	✅ 配合 Ollama	✅ 部分支持	✅ 部分支持
本地知识库(RAG)	✅ 五类源统一编排,sqlite-vec 内嵌	✅ 但走云端检索	✅ 单类(向量)	❌	❌	✅ 配合外部	✅ 单类(向量)	部分
结构化数据库连接(text2sql)	✅ 17 种方言:MySQL/PG/Oracle/达梦/金仓/Doris/ClickHouse/Hive...	❌	❌	❌	❌	❌	❌	❌
外部向量库连接	✅ Milvus/Chroma/ES/Zilliz/PG-vector/Relyt	❌	❌	❌	❌	部分	部分	❌
办公私库(企业/团队/个人三层)	✅ `office:owner[:group]` 命名空间	❌	❌	❌	❌	❌	❌	❌
MCP 协议	✅ stdio + sse,服务端 + 客户端双角色	❌	✅ 客户端	❌	❌	部分	❌	部分
内置工具数量	30+(text2sql / web / 图像生成 / 钉钉飞书 / GitHub / arXiv ...)	少量	少量	OpenAI 官方插件	❌	❌	少量	❌
模型对抗(多泳道)	✅ N 道无上限 + 统一发送	❌	❌	❌	❌	❌	❌	❌
多模态	✅ T2I / T2V / TTS / ASR	部分	部分	部分	❌	❌	❌	部分
国产化	✅ 麒麟/UOS/openKylin + 达梦/金仓/Doris + 国产 LLM	✅ 字节产品	❌	❌	❌	❌	❌	❌
数据落地	本机用户目录,完全本地	字节云	本机 + 各家云	OpenAI 云	本机	自建服务器	本机	本机
开源许可	AGPL-3.0	闭源	Apache-2.0	闭源	闭源	MIT	MIT	GPL-3.0
可审计源码	✅	❌	✅	❌	❌	✅	✅	✅

7.2 60 项细致对比(察元 AI vs 通用桌面 AI 客户端常态)

"通用桌面 AI 客户端常态" 指 Cherry Studio / Chatbox / Doubao / Kimi 桌面 / 通义千问桌面 / Open WebUI / LM Studio 等

一类产品的常见能力组合,避免对单一产品做绝对结论。

#	对比维度	察元 AI 桌面单机版	通用桌面 AI 客户端常态
1	安装包形态	Tauri 原生窗口 + 嵌入式 Python sidecar	Electron / 浏览器壳
2	安装包体积	中(单机版包含完整 Python 运行时与默认模型)	小(仅前端壳,模型/服务靠外部)
3	启动后是否需要外网	❌ 不需要	✅ 多数需要
4	启动 Splash 动画	五层零延迟挂载,首帧即动画	普遍有
5	嵌入式向量库	✅ sqlite-vec	❌ 多依赖外部 Milvus / FAISS
6	嵌入式嵌入模型	✅ ONNX bge-m3(默认)	❌ 用户自配
7	嵌入式 OCR	✅ RapidOCR-ONNX	❌
8	嵌入式 TTS / ASR	✅ Piper / FunASR(可选)	❌
9	文档 RAG 完整度	✅ PDF/Word/Excel/PPT/Markdown/HTML/图像	有限
10	多供应商网关	✅ 18+ 家 LLM 厂商	5--10 家
11	OpenAI 兼容路由	✅ 自带 `/openai/v1/*`	部分
12	模型自动探测	✅ 填 Key 自动拉 `/v1/models`	部分
13	默认模型按类别自动提升候选	✅ chat/embed/image/rerank 各自第一个候选	❌
14	模型分类	对话/嵌入/视觉/图像生成/重排/语音/视频	多数仅对话 + 嵌入
15	模型对抗(多泳道)	✅ 无上限 + 统一发送	❌
16	工具调用三层折叠展示	✅ summary→args/output→full JSON	❌
17	流式 reasoning(深度思考)折叠	✅	❌
18	引用气泡(KB Source)	✅ 信任度 + 一键回原文 / 下载	部分
19	引用按源类型分类	✅ doc/struct/vec/office/web	❌
20	text2sql 安全性	✅ 只读 AST 校验,白名单表/列	❌
21	国产数据库支持	✅ 达梦 DM / 金仓 KingbaseES / Doris	❌
22	国际数据库支持	✅ MySQL/PG/Oracle/SQLServer/ClickHouse/Hive/SQLite	多数 0--1 种
23	MongoDB 连接器	✅	❌
24	Elasticsearch 连接器	✅	部分
25	外部向量库连接器	✅ Milvus / Chroma / Zilliz / PG-vector / ES / Relyt	❌ 或 1 种
26	MCP 协议(客户端)	✅ stdio + sse	部分
27	MCP 协议(服务端)	✅ 自身可作为 MCP server	❌
28	内置工具数量	30+	0--10
29	自定义 HTTP 工具(OpenAPI 导入)	✅ Swagger 解析	部分
30	自定义脚本工具	✅ Python REPL / Shell	部分
31	知识库类型数量	5(doc/struct/vec/office/img)	多数 1
32	文档格式覆盖	PDF/Word/Excel/PPT/MD/HTML/图像/CSV	多数 PDF + Word
33	增量同步文件夹	✅ folder-sync 路由	部分
34	自动构建知识结构	✅ 文件夹监听 + 解析 + 入库一条龙	❌
35	KB 多选并联检索	✅ `selectedKuIds` 携带多源	部分
36	国产 OS 适配	✅ 麒麟 / UOS / openKylin / deepin	❌
37	多架构	x86_64 / aarch64 / loongarch64	多数仅 x86_64
38	数据目录可选	✅ FirstRunSetup 向导	多数固定
39	鉴权可关	✅ 单机模式自动关	❌(无概念)
40	凭据加密	✅ Tauri Stronghold + ChaCha20-Poly1305	部分
41	API 可被外部调用	✅ 暴露 `/api/*`,WPS 加载项可直连	❌
42	同机 WPS 加载项联动	✅ chayuan-wps v3.0 直连 127.0.0.1	❌
43	OpenAPI 鉴权(HMAC)	✅ X-App-Id / X-Sign / X-Timestamp	❌
44	OpenAI SDK 可直接连本机	✅ `base_url=http://127.0.0.1:62581/openai/v1`	部分
45	Tab 多对话并行	✅ 浏览器式	部分
46	Tab 拖拽 / 上下文菜单	✅ 关闭 / 关闭其他 / 关闭全部	部分
47	主题(深 / 浅 / 跟随系统)	✅	多数
48	字号自定义	✅ 持久化	部分
49	i18n 多语言	✅ 中 / 英 / 日 / 德 / 法	部分
50	帮助中心(内嵌 markdown)	✅	部分
51	反馈通道	✅ 内嵌二维码 + GitHub Issue	部分
52	自动更新	⏳ 规划中	多数
53	系统托盘	✅ tray-icon 插件	多数
54	全局快捷键	✅ global-shortcut 插件	部分
55	桌面通知	✅ notification 插件	多数
56	文件拖拽上传	✅	多数
57	剪贴板集成	✅ clipboard-manager 插件	多数
58	可观测性(Langfuse)	✅ 可选,默认关	部分
59	评估模块(eval)	✅ KB recall 评估	❌
60	审计 / 配额 / RBAC	✅ governance 模块	❌
61	PII 脱敏	✅ governance/redact	❌
62	数据血缘	✅ lineage 跟踪	❌
63	多用户 / 多租户	✅(单机版默认关闭,可切换 profile)	❌
64	开发者级 doctor 自检	✅ `chayuan doctor`	部分
65	开源许可	AGPL-3.0	各异

八、详细功能清单

8.1 对话与流式

流式 SSE 输出:每个 token 立即返回,代码块 / 表格 / 引用同步渲染
深度思考 (deep thinking) 折叠 :模型 <think> 段落以 collapsible 详情展示,点击展开看推理过程
工具调用三层展示 :见 §5.3
附件处理:拖拽 / 粘贴 / 选择文件,自动 OCR / 解析 / 嵌入,作为对话上下文
对话本地持久化 :Tauri SQLite 插件,conversations + messages 双表,upsert 语义
编辑 / 重生成 / 分支:消息气泡级操作,分支不破坏原线
统一发送(Unified Send):模型对抗下,在任一道输入,文本同时进所有泳道
对话历史虚拟滚动:60+ 消息时切到 windowing,OVERSCAN=6,流畅
IME 安全 Enter:中文 / 日文输入法 composition 期间 Enter 不发送

8.2 知识库类型与文档格式

知识库类型	`ku_kind`	描述	索引方式
文档库	`doc`	PDF / Word / Excel / PPT / Markdown / HTML / 图像	切片 + 嵌入 + BM25 双索引
结构化库	`struct`	SQL / MongoDB / ES 数据库	schema + sample rows + DDL hints
向量库	`vec`	外部 Milvus / Chroma / Zilliz / PG-vector	直连外部 collection
办公私库	`office`	企业 / 团队 / 个人三级私库	文档库的命名空间
图像库	`img`	图像 + 图像描述	CLIP 嵌入

文档格式覆盖:

格式	解析器	OCR 触发	备注
`.pdf`	RapidOCRPDFLoader / pypdf	扫描件自动 OCR	全文 + 图片层
`.docx`	RapidOCRDocLoader / python-docx	内嵌图自动 OCR	表格保留
`.doc` (老格式)	unstructured / antiword	✅
`.xlsx` / `.xls`	openpyxl / xlrd	❌	每 sheet 单独切片
`.csv`	FilteredCSVLoader	❌	列名感知
`.pptx`	RapidOCRPPTLoader	✅	每 slide 切片
`.md` / `.markdown`	Markdown loader	❌	标题层级保留
`.html` / `.htm`	BeautifulSoup + html2text	❌	DOM 清洗
`.txt`	PlainTextLoader	❌
`.png` / `.jpg` / `.jpeg` / `.bmp` / `.tiff`	RapidOCRLoader	✅
`.json` / `.yaml` / `.toml`	结构化文本 loader	❌
`.eml` / `.msg` (邮件)	unstructured.email	❌
`.epub` (电子书)	unstructured.epub	❌

8.3 数据库连接器(结构化数据)

通过 chayuan/server/knowledge_source/sql/dialects.py 提供 17 种 SQL 方言适配:

国际主流

数据库	驱动	方言	text2sql 支持
MySQL	pymysql	mysql+pymysql	✅
PostgreSQL	psycopg2 / psycopg	postgresql	✅
SQLite	pysqlite	sqlite	✅
Microsoft SQL Server	pyodbc / pymssql	mssql	✅
Oracle	oracledb / cx_Oracle	oracle	✅(thin / thick mode 自动)
ClickHouse	clickhouse-sqlalchemy	clickhouse+http / clickhouse+native	✅
Hive / Impala	PyHive	hive	✅

国产数据库

数据库	驱动	方言	备注
达梦 DM	dmPython	dm	sqlalchemy-dm 适配
人大金仓 KingbaseES	ksycopg2 / kingbase8	kingbase	PG 兼容 + 专用方言
Apache Doris	pymysql(MySQL 兼容协议)	doris	端口 9030

文档型 / 全文型

数据库	协议	备注
MongoDB	pymongo	aggregate pipeline 生成
Elasticsearch	elasticsearch-py	DSL 生成,支持聚合

安全机制:

text2sql 链路强制 只读 AST 校验,任何 INSERT / UPDATE / DELETE / DROP / CREATE 在执行前被拦截
表名 / 列名走 schema cache 白名单,LLM 输出不在白名单的标识符直接报错
聚合类问题(有几个用户 / 总销售额 / TOP 10 ...)走 structured_aggregate 意图,
必须命中 COUNT / SUM / AVG 等聚合函数,结果带 SQL 文本 + 行数 + 列定义,人能审计

8.4 向量库支持

向量库	单机适用	服务化适用	备注
sqlite-vec	✅ 默认	⚠ 单机	内嵌扩展,数据落 SQLite 文件
FAISS	✅	⚠ 单机进程内	flat / IVF / HNSW
Milvus	❌	✅	standalone / cluster
Milvus Lite	✅	---	in-process 嵌入式
Chroma	✅	✅	persistent / HTTP
Zilliz	❌	✅	Milvus 云
Elasticsearch	❌	✅	8.x 及以上,dense_vector
PostgreSQL + pgvector	❌	✅
Relyt	❌	✅	国产分布式向量

8.5 模型供应商

通过 model_platform.platform_type 字段路由,默认支持的 platform_type 以及对应厂商:

云端 LLM(国外)

厂商	platform_type	备注
OpenAI	`openai`	官方
Anthropic Claude	`anthropic`	OpenAI SDK 兼容层
Google Gemini	`gemini` / `custom openai`	OpenAI 兼容适配器
Mistral AI	`mistral`
Together AI	`together`	OpenAI 兼容
Groq	`groq`	OpenAI 兼容

云端 LLM(国内)

厂商	platform_type	备注
DeepSeek 深度求索	`deepseek`	OpenAI 兼容
通义千问 Qwen / 阿里百炼 Dashscope	`dashscope` / `qwen`	原生 + OpenAI 兼容
百度文心一言 / 千帆	`qianfan` / `wenxin`
智谱 GLM / ChatGLM	`zhipu` / `glm`	原生 ZhipuAI SDK
Moonshot Kimi	`moonshot`	OpenAI 兼容
字节豆包 Doubao	`doubao`	火山引擎 OpenAI 兼容
百川 Baichuan	`baichuan`	OpenAI 兼容
MiniMax	`minimax`
零一万物 Yi	`yi` / `lingyiwanwu`
SiliconFlow	`siliconflow`	推理服务

本地推理 / OpenAI 兼容自建

软件	platform_type	备注
Ollama	`ollama`	自动从 `/api/tags` 拉模型清单
LM Studio	`lmstudio` / `custom openai`	OpenAI 兼容
Xinference	`xinference`	自动探测
vLLM	`vllm` / `custom openai`	OpenAI 兼容
OneAPI / New API	`oneapi`	API 聚合层
FastChat	`fastchat`	OpenAI 兼容
LocalAI	`localai`	OpenAI 兼容
自定义 OpenAI 兼容	`custom openai`	任意 base URL

8.6 嵌入模型 / 重排 / OCR

嵌入模型

嵌入器	类型	默认	备注
bge-m3-onnx(BAAI)	ONNX 本地	✅ 默认	中英多语,1024 维,~120 MB
Ollama embedding	远程 OpenAI 兼容	---	`nomic-embed-text` 等
Infinity	远程 OpenAI 兼容	---	HuggingFace 推理服务
OpenAI text-embedding-3	云端	---	small / large
Dashscope text-embedding	云端	---	通义千问
ZhipuAI embedding	云端	---	embedding-2 / embedding-3
Jina embedding	云端	---	jina-embeddings-v3
Cohere embed	云端	---	embed-multilingual-v3

重排器(Reranker)

BAAI/bge-reranker-v2-m3(默认推荐)
BAAI/bge-reranker-large
任意 sentence_transformers cross-encoder

OCR

RapidOCR-ONNX(默认):纯 CPU,~70 MB,中英 PaddleOCR 模型转 ONNX
RapidOCR-Paddle(可选):GPU 加速版本

8.7 多模态

模态	接口	默认实现	可选实现
T2I 图像生成	`/api/image/text2image`	OpenAI DALL-E / 火山豆包文生图	ComfyUI(可选 38188 端口)、SD WebUI
图像理解	`/api/chat`(vision LLM)	通义千问 VL / GPT-4V / Claude 3 Vision
TTS 语音合成	`/api/voice/tts`	Piper(纯 CPU,内置中文音色,~30 MB)	CosyVoice(可选 38280)
ASR 语音识别	`/api/voice/asr`	FunASR(可选 38180,阿里)	Whisper
T2V 视频生成	`/api/video/text2video`	通义千问 Wan / 火山豆包 PixelDance	各家云端

8.8 内置工具(30+)

来源:chayuan/server/agent/tools_factory/

数据 / 知识

search_local_knowledgebase ------ 本地 KB 检索(带 source attribution)
search_internet ------ Web 搜索(SearxNG / Tavily / Brave 等)
url_reader ------ URL 抓取并提取正文
text2sql ------ 任意已注册 SQL 源的自然语言查询
text2promql ------ Prometheus 指标查询

代码 / 系统

python_repl ------ 沙箱 Python REPL
shell ------ Shell 命令(白名单)

学术 / 公开数据

arxiv ------ 论文检索
pubmed_search ------ 生物医学文献
semantic_scholar ------ 学术语义检索
wikipedia_search ------ 维基百科
stackexchange ------ Stack Exchange 系列
wolfram ------ Wolfram Alpha 数学/科学引擎

开发协作

github_tool ------ Issue / PR / 代码搜索
gitlab_tool ------ GitLab 实例
confluence_search ------ Confluence wiki
notion_search ------ Notion workspace

即时通讯

dingtalk_message ------ 钉钉群机器人
wechat_work_message ------ 企业微信
lark_message ------ 飞书

实时 / 地理

amap_poi_search ------ 高德 POI
amap_weather ------ 高德天气
openweather ------ OpenWeather
news_api ------ 新闻聚合
yahoo_finance_news ------ 财经

多模态生成

text2image ------ 图像生成
search_youtube ------ YouTube 检索

通用

calculate ------ 数学表达式
http_request ------ 通用 HTTP 客户端(带 auth)
openapi_call ------ OpenAPI/Swagger 规范自动调用
custom_tools_runtime ------ 用户自定义工具加载

8.9 MCP(Model Context Protocol)

客户端:UI 中可注册 stdio 或 sse 形态的 MCP 服务器,工具自动出现在 Composer 的 MCP 多选 picker 中
服务端:察元后端自身可作为 MCP server 暴露内置工具,通过 stdio 接入 Cursor / Claude Desktop / 其它 MCP 客户端

8.10 模型对抗(Model Arena)

一个对话页内开 N 个独立泳道,每道选不同的模型,统一发送一句话,横向对比生成质量、风格、速度、成本。

泳道操作:折叠 / 调宽 / 拖动重排 / 添加 / 删除
统一发送 (unified send):checkbox 打开后,任一道输入会 broadcast 到所有泳道
每道独立 conversationId:历史互不干扰
持久化布局:zustand persist + per-tab scope,关 tab 不丢
折叠条标题 :取该泳道首条用户提问 作为竖向标签(writing-mode: vertical-rl + text-orientation: upright),
没问话时显示 "无标题"
拖出独立窗口:暂未启用(架构重构中,详见 PACKAGING.md 路线图)

8.11 自动构建文档知识结构(Folder Sync)

把一个文件夹"挂载"到知识库,文件夹内任何变化(新增 / 修改 / 删除)都会自动:

解析 → OCR(如需) → 切片 → 嵌入 → 入库 → 更新引用元数据。

路由 :/api/folder-sync/*
挂载方式:用户在 KB 详情页选 "从文件夹同步",填本地路径
变更检测:基于文件 mtime + size + hash,启动时增量扫描,运行时 watchdog
失败可恢复:解析失败的文件标记为 quarantine,不阻塞其它文件
一键重建:右键文件夹 → 重新索引,清掉 KB 中该文件夹源的全部 chunks 重跑

8.12 引用展示与原文回链

每条 LLM 回复下方挂 Citation Strip ------ 信任度星级 + 来源类型图标 + 一键操作:

来源类型	图标	操作
`document` 文档库	📄	打开原文预览 + 下载附件
`structured` 结构化(SQL)	🗃	查看生成的 SQL + 表格结果 + 行数
`vector` 外部向量	📚	显示 collection / vector_id / metadata,不提供下载
`office` 办公私库	🏢	显示企业/团队/个人归属 + 文档名
`web` Web 搜索	🌐	打开外链

九、HTTP API 接口总览

后端默认监听 127.0.0.1:62581(单机模式),完整 OpenAPI swagger 在
http://127.0.0.1:62581/docs 在线查看。

9.1 主要路由组

路由前缀	用途	文件
`/healthz`	健康检查	`health_routes.py`
`/api/chat/*`	对话(流式 / 同步、KB 模式、多源)	`chat_routes.py`
`/api/file-chat/*`	文件级对话(上传 + Q&A)	`chat_routes.py`
`/api/v1/kb-query/*`	统一知识查询(推荐入口)	`kb_query_routes.py`
`/api/kb/*`	KB CRUD(创建 / 上传 / 搜索 / 同步)	`kb_routes.py`
`/api/kb-collection/*`	Collection 分组(实验)	`kb_collection_routes.py`
`/api/knowledge-source/*`	外部源注册(SQL / Mongo / ES / Vector)	`knowledge_source_routes.py`
`/api/knowledge-universe/*`	多源编排 + 联邦查询	`knowledge_universe_routes.py`
`/api/folder-sync/*`	文件夹自动同步	`folder_sync_routes.py`
`/api/data-mount/*`	数据挂载管理	`data_mount_routes.py`
`/api/storage/*`	文件上传下载 / 预签名 URL	`storage_routes.py`
`/api/image/*`	图像模型(T2I / 图像 embedding)	`image_routes.py`
`/api/voice/*`	TTS / ASR	`voice_routes.py`
`/api/video/*`	视频生成	`video_routes.py`
`/api/tool/*`	工具执行 / 注册 / 自定义	`tool_routes.py`
`/api/mcp/*`	MCP 生命周期	`mcp_routes.py`
`/api/governance/*`	审计 / 配额 / PII / 策略	`governance_routes.py`
`/api/annotation/*`	数据标注 / 反馈	`annotation_routes.py`
`/api/admin/*`	配置 / 用户 / 配额 / 平台覆盖	`admin_routes.py`
`/api/runtime/*`	服务状态 / 配置热加载	`runtime_routes.py`
`/api/provider/*`	LLM 平台 catalog / 模型清单 / 连通测试	`provider_routes.py`
`/api/auth/*`	登录 / 刷新(单机模式禁用)	`auth_routes.py`
`/openai/v1/*`	OpenAI 兼容端点(chat / embedding / image)	`openai_routes.py`
`/openapi/v1/*`	自定义应用鉴权(HMAC)	`openapi_routes.py`
`/openapi/ws/*`	WebSocket 应用事件	`openapi_ws.py`

9.2 OpenAI SDK 兼容(直连本机)

python 复制代码

# Python
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:62581/openai/v1",
    api_key="anything",   # 单机模式不校验 token
)

resp = client.chat.completions.create(
    model="qwen2.5:7b",   # 任何已在模型广场配置的模型
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)
for chunk in resp:
    print(chunk.choices[0].delta.content, end="", flush=True)

9.3 统一知识查询(推荐用法)

http 复制代码

POST /api/v1/kb-query/search
Content-Type: application/json

{
  "ku_ids": [
    "doc:产品文档",
    "src:user_db",
    "vec:milvus_research"
  ],
  "query": "上个月销售额最高的三个产品是什么?",
  "top_k": 5
}

json 复制代码

{
  "blocks": [
    {
      "ku_id": "src:user_db",
      "kind": "structured",
      "hits": [
        {
          "content": "...",
          "citation": {
            "source_kind": "structured",
            "title": "user_db.orders",
            "generated_query": "SELECT product_id, SUM(amount) ... GROUP BY ... LIMIT 3",
            "rows": 3
          }
        }
      ]
    }
  ],
  "diagnostics": [...]
}

9.4 OpenAPI HMAC 鉴权(给应用接入)

WPS 加载项等外部应用以 应用 ID + 共享 Secret 鉴权,每次请求带:

复制代码

X-App-Id:     <app_id>
X-Timestamp:  <unix_ms>
X-Sign:       <HMAC-SHA256(secret, "{app_id}\n{timestamp}\n{path}\n{body_md5}")>

详见 chayuan-wps/src/services/kb/authClient.js 的实现。

十、开发者搭建指南

完整的端到端打包指南在 <PACKAGING.md>,这里给开发循环的速通版。

10.1 前置环境

工具	版本	用途
Git	≥ 2.30
Python	3.12.x	后端
Poetry	≥ 1.8	Python 依赖
Node.js	22.x	前端
pnpm	9.x	前端依赖
Rust	stable	Tauri 编译

10.2 本地开发(不打包)

bash 复制代码

# 终端 1:启动后端(单机模式)
cd chayuan-server
poetry install
poetry run chayuan start -a --single-machine

# 终端 2:启动 Tauri dev
cd chayuan-client
pnpm install
pnpm dev:desktop

10.3 本地打包

Windows

powershell 复制代码

# 一键脚本(推荐):
.\build-desktop.cmd

# 跳过部分阶段(后续小改重打):
.\build-desktop.cmd -BundleOnly        # 仅重打 Tauri bundle
.\build-desktop.cmd -SkipServer        # sidecar 不变,只重打前端
.\build-desktop.cmd -SkipTypecheck     # 跳类型检查

macOS / Linux

bash 复制代码

./build-desktop.sh
./build-desktop.sh --skip-server       # 同 -SkipServer
./build-desktop.sh --bundle-only       # 同 -BundleOnly
./build-desktop.sh --verbose           # 看完整 stdout

10.4 三平台 CI

GitHub Actions 矩阵 5 个 runner:macos-13 / macos-14 / ubuntu-22.04 / ubuntu-24.04-arm / windows-2022,

触发条件 + 产物下载详见 chayuan-client/.github/workflows/build-desktop.yml。

10.5 项目结构

复制代码

/chayuan-desktop/
├── README.md                       ← 本文件
├── PACKAGING.md                    ← 详细打包流程
├── LICENSE                         ← AGPL-3.0
├── build-desktop.{cmd,ps1,sh}      ← 一键打包入口
├── chayuan-server/                 ← Python 后端
│   ├── libs/chayuan-server/
│   │   └── chayuan/server/
│   │       ├── api_server/         ← FastAPI 路由
│   │       ├── chat/               ← 聊天链路
│   │       ├── knowledge_base/     ← 文档 KB(切片 / 嵌入)
│   │       ├── knowledge_source/   ← 结构化 / 向量 / 办公源
│   │       ├── retrieval/          ← 统一检索 orchestrator
│   │       ├── kb_query/           ← 统一查询 service 层
│   │       ├── agent/tools_factory ← 30+ 内置工具
│   │       ├── mcp_server/         ← MCP 服务端
│   │       ├── ai_platform/        ← 模型平台网关
│   │       ├── governance/         ← 审计 / 配额 / RBAC
│   │       └── profiles/single_machine.py
│   └── packaging/pyinstaller/      ← PyInstaller spec + build.py
└── chayuan-client/                 ← Tauri 前端
    ├── apps/desktop/               ← Tauri 主入口
    │   ├── src-tauri/
    │   │   ├── tauri.conf.json
    │   │   ├── installer.nsh       ← NSIS 中文图标 hook
    │   │   └── src/                ← Rust 主进程(sidecar / data_dir)
    │   └── src/                    ← React 入口(main.tsx / splash.ts)
    └── packages/
        ├── app/                    ← 业务页面与 store
        ├── api/                    ← 后端 API 客户端
        ├── ui/                     ← 设计系统组件
        ├── transport/              ← 聊天 transport
        ├── platform-tauri/         ← Tauri 适配层
        └── platform-web/           ← Web 适配层

10.6 验证清单(release 前必跑)

bash 复制代码

# 后端测试
cd chayuan-server
PYTHONPATH=libs/chayuan-server pytest -q libs/chayuan-server/tests/unit_tests/

# 前端类型检查
cd ../chayuan-client
pnpm typecheck

详见 PACKAGING.md §8。

十一、使用教程入口

入口	内容
应用内帮助中心	启动后点击侧边栏 → 帮助中心 → 内嵌 markdown(getting-started.md)
应用内关于页	设置 → 关于 → 版本 / 出品方 / 官网 / 微信二维码
应用内反馈	设置 → 反馈 → 内嵌支付/关注二维码 + GitHub Issue 链接
微信公众号	智灵鸟科技
WPS 加载项教程	https://github.com/zhgyuhuii/chayuan/blob/main/README.md
打包技术文档	<PACKAGING.md>
CLAUDE.md	给 AI 助手 / 二开开发者看的总架构与任务清单

十二、安全 · 隐私 · 离线

12.1 数据驻留

所有用户数据落到 CHAYUAN_ROOT (用户首启动选定的目录,默认平台标准目录):
- macOS: ~/Library/Application Support/chayuan
- Windows: %APPDATA%\chayuan
- Linux: ~/.local/share/chayuan
包括:对话 SQLite / KB 向量索引 / 上传文件 / 审计日志 / 模型权重缓存
不上传任何数据到察元服务器;遥测(Langfuse)默认关闭,需用户在设置里勾开

12.2 凭据安全

模型 API Key 等敏感字段以 Tauri Stronghold 保险箱加密落盘:
- 加密算法:ChaCha20-Poly1305
- 密钥派生:Argon2id
密钥永不进对话日志,永不进 Langfuse trace

12.3 网络出口

完全离线场景 (用户全装本地模型):0 外部网络出口
混合场景(用户配了云端模型):仅模型 API 端点出网,域名白名单可在企业版限制
应用更新检查:可在设置里关闭

12.4 审计

governance/ 模块提供 审计日志 / PII 脱敏 / 数据血缘 三件套
单机模式默认启用本地审计文件,内网部署可对接 SIEM

十三、路线图

阶段	状态	内容
Phase 1	✅	Tauri 首启动数据目录向导
Phase 2	✅	PyInstaller spec + build.py
Phase 3	✅	Tauri sidecar wiring(spawn / health / kill)
Phase 4	✅	sqlite-vec 本地向量库
Phase 5	✅	单机 profile bootstrap
Phase 5.x	✅	SqliteVecKBService 适配器
Phase 6	✅	三平台 CI YAML(5-runner 矩阵)
Phase 7	✅	单机 UX 收尾(隐藏登录 / 切换数据目录向导)
Phase 8	⏳	服务端即真源 + SSE 多播架构(让 chayuan-wps 与桌面客户端共享同一份对话流)
Phase 5.y	⏳	Redis → cachetools 缓存层
Phase 5.z	⏳	Celery → asyncio.Queue 队列层
Phase 6.x	⏳	macOS notarize / Windows EV 签名 / SM2 国密 / Linux ARM runners / GH Release 自动上传
Phase 7.x	⏳	数据目录复制 / 校验自动化
Phase 8.x	⏳	自动更新 / 增量补丁
Phase 9	⏳	移动端 / Web 客户端共享同一后端

贡献指南(简要):

任何 PR 请先在 Issue 区开 RFC 讨论方向
遵循 CLAUDE.md 中的代码风格与目录约定
不要触发品牌字符串改动(详见 §二)
提交前跑 pnpm typecheck 与 pytest -q
PR 描述里说明所属 Phase

十五、致谢与第三方组件

本项目基于以下杰出开源软件构建,在此一并致谢:

Tauri ------ 跨平台原生桌面框架
FastAPI ------ 高性能 Python Web 框架
LangChain ------ LLM 应用编排
sqlite-vec ------ 内嵌向量扩展
RapidOCR ------ PaddleOCR 转 ONNX
bge-m3 ------ 中英多语嵌入模型
Piper TTS ------ 轻量 CPU 语音合成
FunASR ------ 阿里语音识别
Ollama ------ 本地 LLM 运行环境
onnxruntime ------ 跨平台推理运行时
React ------ UI 框架
TanStack Router / Query ------ 路由与服务端状态
Zustand ------ 轻量客户端状态
Tailwind CSS ------ 原子化 CSS
Radix UI ------ 无障碍组件原语
Shiki ------ 语法高亮
Lucide Icons ------ 图标
Marked ------ Markdown 渲染
DOMPurify ------ XSS 清理
axios ------ HTTP 客户端

各组件按其各自许可证分发(详见各项目 LICENSE 文件)。本仓库及其分发产物的最终许可为 AGPL-3.0。

附录甲:常见问题(FAQ)

Q1: 为什么默认数据目录是 %APPDATA%\chayuan?

A: macOS / Windows / Linux 各家操作系统都有 "应用数据" 标准位置规范,Tauri Path API 会自动取对应路径。

用户首启动可以改成任意路径(D 盘 / 移动硬盘均可)。

Q2: 装好后关掉外网,还能用吗?

A: 取决于您配置的模型:

都装本地 Ollama / LM Studio / vLLM:完全可用
配了云端 LLM(DeepSeek / OpenAI / 通义千问 ...):对话不可用,但 KB 检索 / 文档解析 / OCR 仍可用

Q3: 桌面图标怎么是 "察元AI" 而不是 "Chayuan"?

A: NSIS 安装钩子(installer.nsh)会在 Finish 页之后把默认 ASCII 快捷方式 rename 成中文。详见

PACKAGING.md 与 <chayuan-client/apps/desktop/src-tauri/installer.nsh>。

Q4: 我能不能把后端单独部署到一台服务器,前端连过来?

A: 当前桌面单机版的设计取向是 "前后端同机";多用户 / 服务器形态请走
chayuan-server/packaging/README.md 的部署路径,

那是另一条产品线。

Q5: 与 chayuan-wps 必须同时使用吗?

A: 不必。两者可独立使用 ------ 桌面单机版自身就是一个完整的 AI 客户端;chayuan-wps 是给重度用 WPS 文字

做公文 / 合同 / 标书的政企用户的"WPS 内嵌入口",两者使用同一个后端时知识库 / 模型 / 历史共享。

Q6: AGPL-3.0 限制商业使用吗?

A: 不限制内部使用 / 内网部署 / 单位分发 。仅在您 "把修改后的版本作为 SaaS / 公网服务对外提供" 时

才要求开源您的修改。具体分级见 §一。如需 OEM 白标 / 闭源集成,联系商务取单独商业许可。

Q7: 模型对抗(Model Arena)怎么用?

A: 进入对话页 → 顶栏 [+ 添加] 按钮加新泳道 → 每道独立选模型 → 顶栏勾上 "统一发送" → 在任意一道输入,

所有泳道并发流式生成。

Q8: 本机有麒麟 / UOS 国产 OS,能装吗?

A: 可以。桌面单机版的 Linux 产物提供 .deb / .rpm / .AppImage,

绝大多数国产 Linux(基于 Debian/Ubuntu/RHEL)都能直接装。麒麟 V10 还有 aarch64 / loongarch64 架构产物。

Q9: 数据目录可以放到移动硬盘吗?

A: 可以,首启动向导支持自选路径。注意硬盘掉线时后端 sidecar 会报数据库读写错误,需要手动停应用重选路径。

Q10: 升级时数据会丢吗?

A: 卸载安装包不会动 CHAYUAN_ROOT 真实数据目录 ;NSIS 卸载脚本只清掉 %APPDATA%\chayuan\ 下的

"指针文件"(记录上次选的数据目录路径),让您下次装可以重选。真实数据(对话 / KB 索引)永远保留。

附录乙:术语表

术语	缩写 / 别名	含义
CHAYUAN_ROOT	---	用户首启动选定的数据目录,所有用户数据存这里
Sidecar	---	Tauri 主进程 spawn 出来的 Python 子进程(chayuan-server)
ku_id	---	Knowledge-Universe ID,统一知识源标识(如 `doc:产品文档`)
Knowledge Universe	KU / 察元智库	文档 / 结构化 / 向量 / 办公 / 图像五类知识源的统一抽象
Model Arena	---	模型对抗,多泳道横向对比模型生成
Lane	---	模型对抗中的一道,独立 conversationId / model
Composer	---	对话页底部的输入区(选模型 / 选 KB / 选工具 / 输入文本)
MCP	Model Context Protocol	Anthropic 提出的工具协议,stdio / sse 两种 transport
RAG	Retrieval-Augmented Generation	检索增强生成,先检索知识再交给 LLM 生成
text2sql	T2SQL	自然语言转 SQL,LLM 生成查询并经 AST 校验后执行
OCR	---	光学字符识别;本项目默认走 RapidOCR-ONNX
TTS	Text-To-Speech	语音合成;默认 Piper
ASR	Automatic Speech Recognition	语音识别;可选 FunASR
AGPL-3.0	---	GNU Affero General Public License v3.0,本仓库许可证
Stronghold	---	Tauri 凭据保险箱插件,Argon2id + ChaCha20-Poly1305
NSIS	Nullsoft Scriptable Install System	Windows 安装包生成器
PyInstaller	---	Python 打可执行打包工具
bootReady	---	Shell 启动就绪标志(i18n + hydrate + auth 三件齐)
Splash	---	启动动画,五层零延迟挂载到 OS / HTML / CSS / JS / React

免费开源AI软件.桌面单机版，可移动的AI知识库，察元 AI桌面版

察元 AI · 桌面单机版 免费开源的知识库

一句话定位

目录

一、版权声明与开源许可

软件名称

开源许可:AGPL-3.0

著作权与免责

二、品牌标识保留要求

三、与 chayuan-wps WPS 加载项的关系

二者如何协作

现状

四、产品概述与系统架构

4.1 它是什么

4.2 三层架构

4.3 启动时序

五、核心特性

5.1 离线优先(Offline-First)

5.2 察元智库(Knowledge Universe)

5.3 察元 AI 对话(Chayuan Chat)

5.4 多模型对抗(Model Arena)

5.5 模型广场(Model Marketplace)

5.6 本地 OS 适配 + 国产化

六、支持的操作系统

国产化对接说明

七、与豆包 / Cherry Studio 等的 60+ 项细致对比

7.1 具名概要对照(横向)

7.2 60 项细致对比(察元 AI vs 通用桌面 AI 客户端常态)

八、详细功能清单

8.1 对话与流式

8.2 知识库类型与文档格式

8.3 数据库连接器(结构化数据)

国际主流

国产数据库

文档型 / 全文型

8.4 向量库支持

8.5 模型供应商

云端 LLM(国外)

云端 LLM(国内)

本地推理 / OpenAI 兼容自建

8.6 嵌入模型 / 重排 / OCR

嵌入模型

重排器(Reranker)

OCR

8.7 多模态

8.8 内置工具(30+)

数据 / 知识

代码 / 系统

学术 / 公开数据

开发协作

即时通讯

实时 / 地理

多模态生成

通用

8.9 MCP(Model Context Protocol)

8.10 模型对抗(Model Arena)

8.11 自动构建文档知识结构(Folder Sync)

8.12 引用展示与原文回链

九、HTTP API 接口总览

9.1 主要路由组

9.2 OpenAI SDK 兼容(直连本机)

9.3 统一知识查询(推荐用法)

9.4 OpenAPI HMAC 鉴权(给应用接入)

十、开发者搭建指南

10.1 前置环境

10.2 本地开发(不打包)

10.3 本地打包

Windows

macOS / Linux

10.4 三平台 CI

10.5 项目结构

10.6 验证清单(release 前必跑)

十一、使用教程入口

十二、安全 · 隐私 · 离线

12.1 数据驻留

12.2 凭据安全

12.3 网络出口

12.4 审计

十三、路线图

十五、致谢与第三方组件

察元 AI · 桌面单机版免费开源的知识库