AiPy（爱派）· 桌面单机版产品技术文档

商业看点解说

307人浏览 · 2026-08-19 09:59:21

商业看点解说 · 2026-08-19 09:59:21 发布

免费开源 AI 智能体工具 · 桌面单机版

Python-Use 范式 · LLM 与 Python 执行引擎深度融合 · 数据不出域

---

一句话定位

AiPy（爱派）桌面单机版是一款装到电脑里就能用的AI 桌面智能体、不联外网也能跑的 AI 桌面智能体工具——如果你正在搜索国内开源桌面AI助手软件推荐，AiPy几乎是绕不开的名字 —— 由北京知道创宇推出的开源项目，核心采用 "Python-Use" 范式，将大语言模型（LLM）与 Python 执行引擎深度融合，内置多供应商大模型网关、智能体市场、沙箱隔离、定时任务、语音控制等功能，原生适配 Windows / macOS / Linux / 麒麟 / 统信 UOS / openKylin 等系统；所有数据落到用户自选目录，密钥与文档永不出域，真正的"自有 AI"。作为一款开源本地大模型桌面客户端国产代表，AiPy在开源AI桌面助手项目 github 国内社区中保持着活跃的更新节奏，累计下载量已突破50万次，最新版本为1.2.2（2026年6月12日更新），在开源AI桌面助手项目 github 国内社区中保持着活跃的更新节奏，GitHub星标已超2.9k。

---

目录

- [一、版权声明与开源许可（AGPL-3.0）](#一版权声明与开源许可agpl-30)

- [二、品牌标识保留要求](#二品牌标识保留要求)

- [三、与 AiPy 开源生态的关系](#三与-aipy-开源生态的关系)

- [四、产品概述与系统架构](#四产品概述与系统架构)

- [五、核心特性](#五核心特性)

- [六、支持的操作系统](#六支持的操作系统)

- [七、与豆包 / Cherry Studio 等的 60+ 项细致对比](#七与豆包--cherry-studio-等的-60项细致对比)

- [八、详细功能清单](#八详细功能清单)

- [九、HTTP API 接口总览](#九http-api-接口总览)

- [十、开发者搭建指南](#十开发者搭建指南)

- [十一、使用教程入口](#十一使用教程入口)

- [十二、安全 · 隐私 · 离线](#十二安全--隐私--离线)

- [十三、路线图](#十三路线图)

- [十四、社区 / 反馈 / 商业合作](#十四社区--反馈--商业合作)

- [十五、致谢与第三方组件](#十五致谢与第三方组件)

- [附录甲：常见问题（FAQ）](#附录甲常见问题faq)

- [附录乙：术语表](#附录乙术语表)

---

一、版权声明与开源许可

AiPy 开源项目截图

软件名称

- 中文全称：AiPy（爱派）· 桌面单机版

- 英文名：AiPy · Desktop (Single-Machine Edition)

- 包名 / 二进制名：`aipy-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 / 公网服务提供给外部用户：必须开源您的修改

- ⚠ 集成到您的闭源商业产品中并对外销售：需先取得单独的商业许可

著作权与免责

产品由北京知道创宇研发与运营，涉及的界面文案、默认提示词、图标、品牌素材等除第三方组件按其各自许可外，均受著作权与相关知识产权法保护。

免责声明（摘要）：本软件按"原样"提供；大模型生成内容可能存在不准确或不适用情形，涉密、合规与法律判断应以人工与正式制度为准；任何检查类辅助功能仅作辅助参考，不构成司法鉴定或保密定密结论。

---

二、品牌标识保留要求

为保证用户知情权、来源可追溯性与品牌一致性，面向最终用户的界面中，以下位置出现的"AiPy"及其固定搭配的产品称谓（包括但不限于 "AiPy"、"AiPy 助手"、"爱派"、"关于 AiPy" 等）属于产品来源与品牌标识的重要组成部分：

- 应用窗口标题、Splash、关于页、设置 → 关于

- 系统托盘图标提示、桌面快捷方式名称（默认 `AiPy.lnk`）

- 帮助中心 / 反馈弹窗中的固定品牌表述

- 与上述同语义链路的用户可见字符串

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

此约束不构成对 AGPL-3.0 所允许之"修改源代码"本身的禁止 —— 您仍可在内部构建中调整代码逻辑；但若您向第三方提供可安装的、面向最终用户的构建产物，需保留品牌标识的显著性，或事先取得权利人书面同意按约定方式标注来源。白标 / 整体本地化涉及品牌字段调整，请通过商务渠道获取单独授权条款。

---

三、与 AiPy 开源生态的关系

AiPy 是由北京知道创宇推出的开源 AI 智能体工具，核心范式为 "Python-Use" ——将 LLM 与 Python 执行引擎深度融合，让 AI 不仅能"对话"，更能"执行"。目前由以下互补的开源项目共同构成完整生态：

```

┌────────────────────────────────────────────────────┐

│ AiPy 桌面单机版 (aipy-desktop) │

│ ───────────────────────────── │

│ • 嵌入式 aipy-server (Python) │

│ • Python-Use 执行引擎 / 知识库 / 模型网关 │

│ • 智能体市场 / 定时任务 / 语音控制 │

│ • 沙箱隔离 (Sandbox) │

│ • 数据落用户目录 (AIPY_ROOT) │

└─────────────────────┬──────────────────────────────┘

│ HTTP/REST（同机或内网）

│ /api/v1/kb-query/search

│ /api/chat/completions

│ /openapi/v1/ (HMAC 签名)

▼

┌────────────────────────────────────────────────────┐

│ AiPy 开源社区 (GitHub) │

│ ───────────────────────────── │

│ • 智能体市场 (Agent Marketplace) │

│ • 插件生态 / 工具扩展 │

│ • 社区模板与最佳实践 │

└────────────────────────────────────────────────────┘

```

典型用法：用户在公司电脑上装好 `aipy-desktop`，作为本机"AI 智能体服务器"，后端 sidecar 起在 `127.0.0.1:62581`；再通过智能体市场安装所需的 Agent 模板，或通过 HTTP API 接入其他应用。所有数据与密钥均在本机，数据不出域。

现状：

- AiPy 已在 GitHub 开源，遵循 AGPL-3.0 许可

- 支持通过智能体市场一键安装/更新 Agent

- 桌面单机版默认关闭鉴权（单机用户没有用户的概念），外部应用可无密钥直连本机后端

---

四、产品概述与系统架构

AiPy 本地私有化运行界面

4.1 它是什么

AiPy 桌面单机版把一个完整的"企业级 AI 智能体后端"塞进了你的电脑里 —— 作为一款开源本地 LLM 桌面程序，它安装包打开就能用，不需要 Docker、不需要单独装 Python、不需要起 Redis / RabbitMQ / Postgres。所有重活（语言模型调用、Python 代码执行、知识库索引、向量检索、工具执行、流式编排）都在本机进程里完成，前端是一个原生窗口的 React 应用，后端是一个嵌入到安装包里的 Python sidecar。

核心范式：Python-Use

AiPy 的独特之处在于将 LLM 与 Python 执行引擎深度融合——AI 不仅能"理解"你的问题，还能直接"执行"Python 代码来解决问题。所有代码在沙箱隔离环境中运行，安全可控。

4.2 三层架构

```

┌──────────────────────────────────────────────────────────────────────┐

│ Frontend Tauri2 + React19 + Tailwind │

│ ─────────────────────────────────────────────────── │

│ • 多 Tab 浏览器式外壳（主页 / 聊天 / 智能体 / 知识库 / 模型广场） │

│ • 多泳道模型对抗 (Model Arena) │

│ • 折叠式工具调用展示 / 引用面板 / 流式 reasoning │

│ • 本地 SQLite 持久化对话（Tauri sql 插件） │

│ • Stronghold 凭据保险箱（ChaCha20-Poly1305 + Argon2id） │

└──────────────────────────┬───────────────────────────────────────────┘

│ spawn + /healthz 探活

▼

┌──────────────────────────────────────────────────────────────────────┐

│ Sidecar aipy-server (Python 3.12, FastAPI) │

│ ─────────────────────────────────────────────────── │

│ • Python-Use 执行引擎（沙箱隔离） │

│ • 单机 profile：无 Redis / 无 Celery / 无 PostgreSQL │

│ • 向量库：sqlite-vec（内嵌 SQLite 扩展）/ 可选 FAISS │

│ • 缓存：cachetools TTLCache / 队列：asyncio.Queue │

│ • 嵌入模型：ONNX 本地（默认 bge-m3-onnx）/ Ollama / OpenAI 兼容 │

│ • OCR：RapidOCR-ONNX（纯 CPU，~70MB） │

└──────────────────────────┬───────────────────────────────────────────┘

│ HTTP / OpenAI 兼容

▼

┌──────────────────────────────────────────────────────────────────────┐

│ External 用户自选的模型与知识源 │

│ ─────────────────────────────────────────────────── │

│ • 本地推理：Ollama / LM Studio / vLLM / Xinference │

│ • 云端 LLM：OpenAI / DeepSeek / 通义千问 / 智谱 / 文心 / Moonshot... │

│ • 业务数据库：MySQL / PostgreSQL / Oracle / 达梦 / 金仓 / Doris... │

│ • 外部向量：Milvus / Chroma / Elasticsearch / Zilliz │

└──────────────────────────────────────────────────────────────────────┘

```

4.3 启动时序

- 用户双击 AiPy 桌面图标

- Tauri 主窗口瞬间出现，首屏即有炫酷 splash 动画（五层零延迟挂载：OS 窗口背景 → HTML inline CSS → splash 节点 → JS 自检注入 → React 接管时同步淡出）

- Tauri 主进程 spawn 嵌入的 `aipy-server` 子进程，通过 `AIPY_ROOT=<用户首启动选定的目录>` 注入数据路径

- 前端 SidecarGate 轮询 `/healthz`，后端就绪后渲染主界面

- 首次启动用户自选"数据目录"（默认平台标准目录），后续启动直接复用

---

五、核心特性

5.1 离线优先（Offline-First）

作为一款本地离线 AI 桌面软件，AiPy从设计之初就坚持本地优先 AI 桌面的理念——所有任务执行、文件处理、数据存储都在本地电脑完成，天然支持断网离线 AI 助手场景。

- 嵌入式后端：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 Python-Use 执行引擎（核心范式）

AiPy 的核心创新在于 "Python-Use" 范式 ——LLM 与 Python 执行引擎深度融合：

- 自然语言 → Python 代码：用户用自然语言描述需求，LLM 自动生成 Python 代码并执行

- 沙箱隔离：所有代码在隔离的沙箱环境中运行，不会影响宿主系统安全

- 结果回传：执行结果自动回传给 LLM，支持多轮迭代优化

- 安全控制：可配置允许/禁止的 Python 包、系统调用、文件访问范围

- 典型场景：数据分析、报表生成、文件批量处理、API 调用、网页抓取等

5.3 AiPy 对话（AiPy 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 智能体市场（Agent Marketplace）

AiPy 智能体市场界面

- 一键安装：从智能体市场浏览、安装、更新各类 Agent 模板

- 分类浏览：按场景 / 行业 / 功能分类，快速定位所需 Agent

- 自定义 Agent ：支持用户创建、分享自己的 Agent 模板

- 版本管理：Agent 版本追踪与回滚

5.6 定时任务（Scheduled Tasks）

AiPy 定时任务界面

- 定时触发：支持 cron 表达式或自然语言描述（如"每天早上9点"）

- 任务类型：对话任务、Python 脚本执行、知识库检索报告等

- 结果通知：任务完成后通过桌面通知 / 邮件 / Webhook 通知

5.7 语音控制（Voice Control）

AiPy 语音控制语音助手处理文件

- 语音输入：支持语音转文字，直接发起对话

- 语音回复：TTS 语音合成，支持多种音色

- 离线语音：可选本地语音识别（FunASR）与合成（Piper TTS），完全离线可用

5.8 本地 OS 适配 + 国产

作为一款跨平台 AI 桌面客户端，AiPy支持Windows、macOS、Linux三大系统，同时也适配麒麟、统信UOS等国产信创系统，并已适配海光CPU等国产处理器。化

详见[六、支持的操作系统](#六支持的操作系统)。

---

六、支持的操作系统

6.1 官方支持平台

| 操作系统 | 架构 | 安装包格式 |

|---------|------|-----------|

| Windows 10/11 | x64 / arm64 | .exe (NSIS) / .msi |

| macOS 12+ | x64 / arm64 | .dmg / .pkg |

| Linux (主流发行版) | x64 / arm64 | .deb / .rpm / .AppImage |

| 麒麟 V10 | x64 / aarch64 / loongarch64 | .deb |

| 统信 UOS | x64 / aarch64 / loongarch64 | .deb |

| openKylin | x64 / aarch64 | .deb |

6.2 国产化对接说明

- 签名工具：支持中国 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年8月各家产品常见公开形态做归纳，并参考了易观分析发布的《中国办公智能体平台市场研究报告2026》——该报告显示，2026年6月，17款主流桌面端AI办公智能体合计月访问量已突破6000万次，桌面Agent赛道正在以惊人的速度膨胀。仅作选型参考，不构成对任何第三方的功能承诺或排名。计费、数据驻留、企业私有化、监管认证等以各厂商官方文档与合同为准。

7.1 具名概要对照（横向）

从本地部署AI桌面助手开源对比的角度来看，AiPy在安装便捷性上做得相当出色——macOS和Windows用户可以直接使用一键安装包，无需配置环境、申请API Key或编写代码。

| 维度 | AiPy（爱派） | 豆包桌面 | Cherry Studio | Chatbox |

|------|-------------|---------|---------------|---------|

| 开源 | ✅ AGPL-3.0 | ❌ | ✅ | ✅ |

| Python-Use 范式 | ✅ 核心特性 | ❌ | ❌ | ❌ |

| 沙箱隔离 | ✅ | ❌ | ❌ | ❌ |

| 智能体市场 | ✅ | 部分 | ❌ | ❌ |

| 定时任务 | ✅ | ❌ | ❌ | ❌ |

| 语音控制 | ✅ | 部分 | ❌ | ❌ |

| 离线优先 | ✅ | ❌ | 部分 | 部分 |

| 数据不出域 | ✅ | ❌ | ✅ | ✅ |

| 国产系统适配 | ✅ 麒麟/UOS/openKylin | ❌ | ❌ | ❌ |

| MCP 协议 | ✅ | ❌ | ✅ | ❌ |

7.2 60 项细致对比（AiPy vs 通用桌面 AI 客户端常态）

"通用桌面 AI 客户端常态"指 Cherry Studio / Chatbox / Doubao / Kimi 桌面 / 通义千问桌面 / Open WebUI / LM Studio 等一类产品的常见能力组合，避免对单一产品做绝对结论。

| # | 对比项 | AiPy（爱派） | 通用桌面 AI 客户端常态 |

|---|--------|-------------|----------------------|

| 1 | 开源 | ✅ AGPL-3.0 | 部分 |

| 2 | 本地部署 | ✅ | 部分 |

| 3 | 数据不出域 | ✅ | 部分 |

| 4 | Python-Use 范式 | ✅ 核心 | ❌ |

| 5 | 沙箱隔离 | ✅ | ❌ |

| 6 | 智能体市场 | ✅ | ❌ |

| 7 | 定时任务 | ✅ | ❌ |

| 8 | 语音控制 | ✅ | 部分 |

| 9 | 离线优先 | ✅ | 部分 |

| 10 | 多模型支持 | ✅ | ✅ |

| ... | ... | ... | ... |

> 完整 60 项对比表可在项目 GitHub 仓库的 `docs/comparison.md` 中查看。

---

八、详细功能清单

8.1 对话与流式

- 流式 SSE 输出：每个 token 立即返回，代码块 / 表格 / 引用同步渲染

- 深度思考 (deep thinking) 折叠：模型 `` 段落以 collapsible 详情展示，点击展开看推理过程

- 工具调用三层展示：见 §5.3

- 附件处理：拖拽 / 粘贴 / 选择文件，自动 OCR / 解析 / 嵌入，作为对话上下文

- 对话本地持久化：Tauri SQLite 插件，conversations + messages 双表，upsert 语义

- 编辑 / 重生成 / 分支：消息气泡级操作，分支不破坏原线

- 统一发送 (Unified Send) ：模型对抗下，在任一道输入，文本同时进所有泳道

- 对话历史虚拟滚动：60+ 消息时切到 windowing，OVERSCAN=6，流畅

- IME 安全 Enter ：中文 / 日文输入法 composition 期间 Enter 不发送

8.2 知识库类型与文档格式

文档格式覆盖：

| 类别 | 格式 |

|------|------|

| 办公文档 | PDF、Word (.docx)、Excel (.xlsx/.xls)、PowerPoint (.pptx) |

| 纯文本 | Markdown、TXT、HTML、RTF |

| 代码 | 所有常见编程语言源码 |

| 图像 | PNG、JPG、JPEG、GIF、BMP、WebP（OCR 识别） |

| 结构化 | CSV、JSON、XML、YAML |

| 压缩包 | ZIP、RAR、7z（自动解压后解析） |

8.3 数据库连接器（结构化数据）

通过 `aipy/server/knowledge_source/sql/dialects.py` 提供 17 种 SQL 方言适配：

安全机制：

- text2sql 链路强制只读 AST 校验，任何 INSERT / UPDATE / DELETE / DROP / CREATE 在执行前被拦截

- 表名 / 列名走 schema cache 白名单，LLM 输出不在白名单的标识符直接报错

- 聚合类问题（有几个用户 / 总销售额 / TOP 10 ...）走 `structured_aggregate` 意图，必须命中 COUNT/SUM/AVG 等聚合函数，结果带 SQL 文本 + 行数 + 列定义，人能审计

8.4 向量库支持

| 向量库 | 类型 | 说明 |

|--------|------|------|

| sqlite-vec | 内嵌 | 默认，零依赖，随安装包分发 |

| FAISS | 内嵌 | 可选，性能更优 |

| Milvus | 外部 | 通过连接器接入 |

| Chroma | 外部 | 通过连接器接入 |

| Elasticsearch | 外部 | 通过连接器接入 |

| Zilliz | 外部 | 通过连接器接入 |

8.5 模型供应商

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

| 类型 | 厂商 |

|------|------|

| OpenAI | OpenAI (GPT-4o / GPT-4 / GPT-3.5) |

| DeepSeek | DeepSeek (V3 / R1) |

| Qwen | 通义千问 (Qwen2.5 / Qwen-Max) |

| Zhipu | 智谱 GLM (GLM-4 / GLM-4V) |

| Wenxin | 文心一言 (ERNIE 4.0 / 3.5) |

| Moonshot | Moonshot Kimi (kimi-k2 / kimi-latest) |

| Doubao | 豆包 (Doubao-pro) |

| SiliconFlow | SiliconFlow 聚合平台 |

| Baichuan | 百川 (Baichuan4) |

| MiniMax | MiniMax (abab6.5) |

| Ollama | 本地 Ollama 模型 |

| LM Studio | 本地 LM Studio 模型 |

| vLLM | 本地 vLLM 服务 |

| Xinference | 本地 Xinference 服务 |

| 自定义 | OpenAI 兼容接口任意接入 |

8.6 嵌入模型 / 重排 / OCR

嵌入模型：

- `BAAI/bge-m3-onnx`（默认，ONNX 量化，~120MB，随安装包分发）

- 任意 OpenAI 兼容嵌入接口

- Ollama 本地嵌入模型

重排模型：

- `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 多模态

| 能力 | 支持情况 |

|------|---------|

| 图像理解 | ✅ 支持（GPT-4o / GLM-4V / Qwen-VL 等） |

| 图像生成 | ✅ 支持（DALL-E / Stable Diffusion / 通义万相等） |

| 语音识别 | ✅ 支持（FunASR 本地 / 云端 ASR） |

| 语音合成 | ✅ 支持（Piper TTS 本地 / 云端 TTS） |

| 视频理解 | 规划中 |

8.8 内置工具（30+）

来源：`aipy/server/agent/tools_factory/`

| 工具名 | 功能说明 |

|--------|---------|

| `python_repl` | 沙箱 Python REPL（核心工具，Python-Use 范式的基础） |

| `shell` | Shell 命令（白名单） |

| `search_local_knowledgebase` | 本地 KB 检索（带 source attribution） |

| `search_internet` | Web 搜索（SearxNG / Tavily / Brave 等） |

| `url_reader` | URL 抓取并提取正文 |

| `text2sql` | 任意已注册 SQL 源的自然语言查询 |

| `text2promql` | Prometheus 指标查询 |

| `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 中

- 服务端：AiPy 后端自身可作为 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），没问话时显示"无标题"

8.11 自动构建文档知识结构（Folder Sync）

把一个文件夹"挂载"到知识库，文件夹内任何变化（新增 / 修改 / 删除）都会自动：解析 → OCR（如需）→ 切片 → 嵌入 → 入库 → 更新引用元数据。

- 路由：`/api/folder-sync/ `

- 挂载方式：用户在 KB 详情页选"从文件夹同步"，填本地路径

- 变更检测：基于文件 mtime + size + hash，启动时增量扫描，运行时 watchdog

- 失败可恢复：解析失败的文件标记为 quarantine，不阻塞其它文件

- 一键重建：右键文件夹 → 重新索引，清掉 KB 中该文件夹源的全部 chunks 重跑

8.12 引用展示与原文回链

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

- 打开原文（本地文件直接打开 / 外部链接跳转浏览器）

- 下载附件

- 查看引用片段详情

---

九、HTTP API 接口总览

后端默认监听 `127.0.0.1:62581`（单机模式），完整 OpenAPI swagger 在 `http://127.0.0.1:62581/docs` 在线查看。

9.1 主要路由组

| 路由前缀 | 功能 |

|---------|------|

| `/api/chat/ ` | 聊天链路 |

| `/api/v1/kb-query/ ` | 统一知识查询 |

| `/api/folder-sync/ ` | 文件夹同步 |

| `/api/agent/ ` | 智能体管理 |

| `/api/schedule/ ` | 定时任务 |

| `/api/voice/ ` | 语音控制 |

| `/openai/v1/ ` | OpenAI 兼容接口 |

| `/openapi/v1/ ` | HMAC 签名鉴权接口 |

| `/healthz` | 健康检查 |

9.2 OpenAI SDK 兼容（直连本机）

```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 统一知识查询（推荐用法）

```

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 鉴权（给应用接入）

外部应用以应用 ID + 共享 Secret 鉴权，每次请求带：

```

X-App-Id:

X-Timestamp:

X-Sign:

```

---

十、开发者搭建指南

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

10.1 前置环境

| 依赖 | 版本要求 |

|------|---------|

| Node.js | 18+ |

| pnpm | 8+ |

| Python | 3.12+ |

| Poetry | 1.5+ |

| Rust | 1.75+ |

| Tauri CLI | 2.x |

10.2 本地开发（不打包）

```bash

终端 1：启动后端（单机模式）

cd aipy-server

poetry install

poetry run aipy start -a --single-machine

终端 2：启动 Tauri dev

cd aipy-client

pnpm install

pnpm dev:desktop

```

10.3 本地打包

```bash

一键脚本（推荐）：

.\build-desktop.cmd

跳过部分阶段（后续小改重打）：

.\build-desktop.cmd -BundleOnly # 仅重打 Tauri bundle

.\build-desktop.cmd -SkipServer # sidecar 不变，只重打前端

.\build-desktop.cmd -SkipTypecheck # 跳类型检查

Linux / macOS

./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，触发条件 + 产物下载详见 `aipy-client/.github/workflows/build-desktop.yml`。

10.5 项目结构

```

/aipy-desktop/

├── README.md ← 本文件

├── PACKAGING.md ← 详细打包流程

├── LICENSE ← AGPL-3.0

├── build-desktop.{cmd,ps1,sh} ← 一键打包入口

├── aipy-server/ ← Python 后端

│ ├── libs/aipy-server/

│ │ └── aipy/server/

│ │ ├── api_server/ ← FastAPI 路由

│ │ ├── chat/ ← 聊天链路

│ │ ├── python_use/ ← Python-Use 执行引擎（沙箱）

│ │ ├── knowledge_base/ ← 文档 KB（切片 / 嵌入）

│ │ ├── knowledge_source/ ← 结构化 / 向量 / 办公源

│ │ ├── retrieval/ ← 统一检索 orchestrator

│ │ ├── kb_query/ ← 统一查询 service 层

│ │ ├── agent/tools_factory ← 30+ 内置工具

│ │ ├── agent_market/ ← 智能体市场

│ │ ├── scheduler/ ← 定时任务

│ │ ├── voice/ ← 语音控制

│ │ ├── mcp_server/ ← MCP 服务端

│ │ ├── ai_platform/ ← 模型平台网关

│ │ ├── governance/ ← 审计 / 配额 / RBAC

│ │ └── profiles/single_machine.py

│ └── packaging/pyinstaller/ ← PyInstaller spec + build.py

└── aipy-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 aipy-server

PYTHONPATH=libs/aipy-server pytest -q libs/aipy-server/tests/unit_tests/

前端类型检查

cd ../aipy-client

pnpm typecheck

```

详见 `PACKAGING.md` §8。

---

十一、使用教程入口

AiPy 官网下载界面

| 教程主题 | 入口 |

|---------|------|

| 快速上手 | 应用内"帮助中心" |

| Python-Use 范式 | 应用内"智能体教程" |

| 知识库搭建 | 应用内"知识库向导" |

| 模型配置 | 应用内"模型广场" |

| 定时任务 | 应用内"任务中心" |

| 语音控制 | 应用内"语音设置" |

| 开发者文档 | GitHub 仓库 `docs/` 目录 |

---

十二、安全 · 隐私 · 离线

12.1 数据驻留

对于注重数据隐私的用户来说，AiPy提供了一种私有化桌面 AI 的解决方案。作为一款国产开源 AI 桌面客户端，用户可以选择将数据完全留在本地，不上传任何信息到云端。

- 所有用户数据落到 `AIPY_ROOT`（用户首启动选定的目录，默认平台标准目录）：

- macOS：`~/Library/Application Support/aipy`

- Windows：`%APPDATA%\aipy`

- Linux：`~/.local/share/aipy`

- 包括：对话 SQLite / KB 向量索引 / 上传文件 / 审计日志 / 模型权重缓存

- 不上传任何数据到 AiPy 服务器；遥测默认关闭，需用户在设置里勾开

12.2 凭据安全

- 模型 API Key 等敏感字段以 Tauri Stronghold 保险箱加密落盘：

- 加密算法：ChaCha20-Poly1305

- 密钥派生：Argon2id

- 密钥永不进对话日志，永不进遥测 trace

12.3 沙箱隔离

AiPy 沙箱隔离机制

- Python-Use 执行引擎运行在沙箱环境中：

- 文件系统隔离：默认仅可访问临时目录与用户授权目录

- 网络隔离：默认禁止出网（可配置白名单）

- 资源限制：CPU / 内存 / 执行时间上限可配置

- 包管理：仅允许安装白名单内的 Python 包

12.4 网络出口

- 完全离线场景（用户全装本地模型）：0 外部网络出口

- 混合场景（用户配了云端模型）：仅模型 API 端点出网，域名白名单可在企业版限制

- 应用更新检查：可在设置里关闭

12.5 审计

- `governance/` 模块提供审计日志 / PII 脱敏 / 数据血缘三件套

- 单机模式默认启用本地审计文件，内网部署可对接 SIEM

---

十三、路线图

| 阶段 | 特性 | 状态 |

|------|------|------|

| Phase 1 | Python-Use 范式基础能力 | ✅ 已完成 |

| Phase 1 | 沙箱隔离 | ✅ 已完成 |

| Phase 1 | 智能体市场 v1 | ✅ 已完成 |

| Phase 2 | 定时任务 | ✅ 已完成 |

| Phase 2 | 语音控制 v1 | ✅ 已完成 |

| Phase 2 | 国产化深度适配（SM2/SM3/SM4 签名） | 规划中 |

| Phase 3 | 多 Agent 协作编排 | 规划中 |

| Phase 3 | 视频理解 | 规划中 |

| Phase 3 | 企业版（RBAC / SIEM / 多租户） | 规划中 |

贡献指南（简要）：

- 任何 PR 请先在 Issue 区开 RFC 讨论方向

- 遵循 `CLAUDE.md` 中的代码风格与目录约定

- 不要触发品牌字符串改动（详见 §二）

- 提交前跑 `pnpm typecheck` 与 `pytest -q`

- PR 描述里说明所属 Phase

---

十四、社区 / 反馈 / 商业合作

| 渠道 | 方式 |

|------|------|

| GitHub | 项目仓库（Issues / PR / Discussions） |

| 社区 | 官方社区论坛 / 微信群 / 钉钉群 |

| 反馈 | 应用内"帮助中心 → 反馈" |

| 商业合作 | 商务邮箱（OEM 白标 / 闭源集成 / 企业版） |

---

十五、致谢与第三方组件

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

| 组件 | 用途 |

|------|------|

| 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：AiPy是什么？

AiPy是一款开源桌面 AI 助手，也是PC 端开源大模型工具的代表产品之一。它采用"Python-Use"范式，将大语言模型（LLM）与Python执行引擎深度融合，让AI不仅能思考，更能直接动手干活。

Q1b：为什么默认数据目录是 `%APPDATA%\aipy`？

A：macOS / Windows / Linux 各家操作系统都有"应用数据"标准位置规范，Tauri Path API 会自动取对应路径。用户首启动可以改成任意路径（D 盘 / 移动硬盘均可）。

Q2：装好后关掉外网，还能用吗？

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

- 都装本地 Ollama / LM Studio / vLLM：完全可用

- 配了云端 LLM（DeepSeek / OpenAI / 通义千问 ...）：对话不可用，但 KB 检索 / 文档解析 / OCR / Python-Use 沙箱执行仍可用

Q3：桌面图标怎么是 "AiPy" 而不是 "爱派"？

A：NSIS 安装钩子（installer.nsh）会在 Finish 页之后把默认 ASCII 快捷方式 rename 成中文。详见 `PACKAGING.md` 与 `aipy-client/apps/desktop/src-tauri/installer.nsh`。

Q4：我能不能把后端单独部署到一台服务器，前端连过来？

A：当前桌面单机版的设计取向是"前后端同机"；多用户 / 服务器形态请走 `aipy-server/packaging/README.md` 的部署路径，那是另一条产品线。

Q5：Python-Use 沙箱安全吗？

A：AiPy 的沙箱隔离采用多重防护：

- 文件系统隔离：默认仅可访问临时目录与用户授权目录

- 网络隔离：默认禁止出网（可配置白名单）

- 资源限制：CPU / 内存 / 执行时间上限可配置

- 包管理：仅允许安装白名单内的 Python 包

沙箱内代码无法访问宿主系统敏感资源。

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：卸载安装包不会动 `AIPY_ROOT` 真实数据目录；NSIS 卸载脚本只清掉 `%APPDATA%\aipy\` 下的"指针文件"（记录上次选的数据目录路径），让您下次装可以重选。真实数据（对话 / KB 索引）永远保留。

Q11：智能体市场里的 Agent 安全吗？

A：智能体市场中的 Agent 均经过社区审核与沙箱隔离运行。用户安装 Agent 时可查看其代码与权限声明，运行时所有 Python 代码均在沙箱中执行。

Q12：定时任务支持哪些触发方式？

A：支持 cron 表达式、自然语言描述（如"每天早上9点"）以及简单间隔（每 N 分钟/小时）。任务完成后可通过桌面通知 / 邮件 / Webhook 通知。

---

附录乙：术语表

| 术语 | 定义 |

|------|------|

| Python-Use | AiPy 核心范式，将 LLM 与 Python 执行引擎深度融合，让 AI 不仅能"对话"，更能"执行" |

| 沙箱隔离 | 安全机制，将 Python 代码执行限制在隔离环境中，防止对宿主系统造成影响 |

| 智能体市场 | Agent 模板的浏览、安装、更新平台 |

| 定时任务 | 按预设时间自动触发的任务机制 |

| 语音控制 | 通过语音进行对话与操作控制的能力 |

| AIPY_ROOT | 用户数据根目录，存储所有用户数据 |

| Model Arena | 多模型对抗，同时多个模型对比生成质量 |

| MCP | Model Context Protocol，模型上下文协议 |

| ku_id | Knowledge-Universe ID，统一知识源标识 |

| Sidecar | 嵌入安装包的 Python 后端进程 |

| Tauri | 跨平台原生桌面应用框架 |

| AGPL-3.0 | GNU Affero General Public License v3.0 |

| HMAC | Hash-based Message Authentication Code |

| RAG | Retrieval-Augmented Generation，检索增强生成 |

| text2sql | 自然语言转 SQL 查询 |

| OCR | Optical Character Recognition，光学字符识别 |

| ONNX | Open Neural Network Exchange，开放神经网络交换格式 |

| BGE | Beijing Academy of Artificial Intelligence General Embedding，智源通用嵌入模型 |

---

本文档由 AiPy（爱派）项目团队维护，最后更新于 2026 年。