OpenYak: 运行在本地设备上的 AI 助手

1. 项目定位

OpenYak 是一款本地优先（Local-First）的桌面端 AI 代理工具，核心定位是为用户提供运行在本地设备上的 AI 助手，替代传统 “云端托管式” AI 工作空间，解决云端 AI 工具的账号绑定、数据隐私、权限管控等问题。

其核心定位可总结为：

无依赖：无需注册 OpenYak 账号，无需绑定付费套餐、席位管理，仅需本地安装即可使用；

本地优先：文件、对话记录、AI 记忆、生成内容、工具权限、工作流状态均存储在本地设备，保障数据隐私；

灵活扩展：支持本地大模型与云端模型无缝切换，兼顾隐私性与功能丰富性；

场景聚焦：面向办公场景，解决多类型办公文件解析、长对话上下文管理、结构化成果生成等核心需求。

2. 核心功能与应用场景

2.1 核心功能

（1）多类型办公文件解析与处理

支持上传并解析 DOCX（文档）、XLSX（表格）、PPTX（演示文稿）、PDF、CSV 等主流办公文件，无需转换格式即可完成内容分析。

（2）结构化成果生成

基于文件内容自动生成可直接复用的办公成果，包括：

备忘录 / 长文档 → 执行摘要、风险点、责任人、后续行动清单、可直接发送的邮件；

表格 / 工作簿 → 预算 vs 实际差异分析、异常数据识别、财务沟通要点；

PPT / 演示文稿 → 逐页内容梳理、证据缺口分析、演讲备注、决策建议；

多文件整合 → 统一的董事会简报（整合备忘录、预算、PPT、PDF 上下文）。

（3）长对话上下文管理

支持超长对话线程，自动压缩冗余信息但保留核心上下文，可基于历史对话继续生成 RACI 矩阵、30 天计划、会议议程等，无需重复说明背景。

（4）多模型灵活切换

本地模型：支持通过 Rapid-MLX、Ollama 运行本地大模型，完全离线使用；

云端模型：支持通过自有密钥（BYOK）调用 OpenRouter、OpenAI、Anthropic、Google 等云端 AI 服务商接口。

（5）远程访问能力

通过扫码建立安全隧道，可从其他设备向本地运行的 OpenYak 发送任务，实现跨设备操控。

（6）故障自愈提示

当文件上传、授权验证、文件解析失败时，自动给出清晰的下一步操作指引，降低使用门槛。

2.2 典型应用场景

企业办公：快速处理海量办公文件，生成结构化汇报材料、决策参考；

个人办公：简化文档 / 表格 / PPT 分析流程，提升办公效率；

团队协作：基于本地文件生成协作清单、会议议程，避免云端数据共享风险；

离线办公：无网络环境下通过本地模型完成基础文件分析。

3. 项目架构

OpenYak 采用模块化架构设计，从文件目录结构可划分为以下核心模块：

3.1 整体架构分层

层级	模块 / 目录	核心作用
桌面应用层	desktop-tauri	基于 Tauri 构建跨平台桌面客户端，提供可视化操作界面，兼容 macOS/Windows/Linux
前端层	frontend	桌面端前端界面实现，支撑用户交互、文件上传、结果展示等功能
后端层	backend	核心业务逻辑层，包含 AI 代理运行时、文件解析、模型调用、数据本地存储等
脚本工具层	scripts	辅助脚本（版本更新、开发环境启动、校验和生成、桌面元数据同步等）
配置 / 文档层	根目录（README、LICENSE 等）	项目说明、许可证、跨平台适配说明（如 [LINUX.md](LINUX.md)）、安全规范等

3.2 核心模块详解

（1）Backend（后端模块）

核心文件：run.py（后端启动入口）、pyproject.toml/requirements.txt（Python 依赖管理）、alembic（数据库迁移工具）；

功能：文件解析逻辑、AI 模型调用适配（本地 / 云端）、本地数据存储、远程访问隧道管理、异常处理等；

配置：.env.example 提供环境变量示例，支持自定义模型、密钥等配置。

（2）desktop-tauri（桌面端模块）

基于 Tauri 框架构建跨平台桌面应用，替代传统 Electron 框架，具备更轻量、更接近原生应用的体验，负责前端界面与后端逻辑的桥接。

（3）Scripts（脚本模块）

包含 .mjs 格式的 Node.js 脚本，用于开发环境启动（dev-all.mjs/dev-desktop.mjs）、版本号更新（bump-version.mjs）、安装包校验和生成（generate-checksums.mjs）等工程化操作。

4. 技术栈说明

基于项目文件结构和功能特性，核心技术栈如下：

4.1 后端技术栈

主语言：Python（后端业务逻辑、文件解析、模型调用）；

数据库迁移：Alembic（基于 SQLAlchemy 的数据库版本管理）；

依赖管理：pip（requirements.txt）、pyproject.toml（现代 Python 项目规范）；

本地模型适配：对接 Rapid-MLX、Ollama 本地大模型运行时；

云端模型适配：OpenAI/Anthropic/Google/OpenRouter API 封装。

4.2 桌面端 / 前端技术栈

跨平台桌面框架：Tauri（替代 Electron，基于 Rust + Web 技术栈，更轻量）；

前端框架：未明确标注，但 Tauri 通常搭配 React/Vue/TypeScript 等主流前端技术；

脚本工具：Node.js（.mjs 脚本，负责工程化操作）。

4.3 跨平台兼容

系统适配：macOS（Apple Silicon/Intel）、Windows（x64）、Linux（x64）；

打包格式：macOS（.dmg/.app）、Windows（.exe 安装包）、Linux（.deb/.rpm）。

5. 安装与部署方式

5.1 生产环境安装（普通用户）

OpenYak 提供预编译的跨平台安装包，直接下载即可使用：

下载渠道：

1GitHub Release：访问 OpenYak 最新发布页；

1官方网站：访问 open-yak.com/download；

分平台安装：

1macOS：下载 .dmg 文件，挂载后将 .app 拖入应用程序文件夹；

1Windows：下载 .exe 安装包，双击执行向导式安装；

1Linux：下载 .deb（Debian/Ubuntu）或 .rpm（CentOS/RHEL）包，通过 dpkg -i/rpm -ivh 安装；

注：Linux 用户需额外参考项目根目录的 LINUX.md，查看系统依赖和故障排查指南。

5.2 开发环境部署（开发者）

（1）环境准备

后端：Python 3.10+、pip、虚拟环境（可选）；

桌面端：Node.js 18+、pnpm/npm、Tauri 环境（参考 Tauri 官方安装指南）；

系统依赖：根据平台安装 Tauri 所需的编译工具（如 Rust、C 编译器）。

（2）代码拉取

bash git clone https://github.com/openyak/openyak.git cd openyak

（3）后端启动

bash cd backend # 安装依赖 pip install -r requirements.txt # 启动后端服务 python run.py

（4）桌面端启动

bash cd desktop-tauri # 安装前端依赖 npm install # 启动开发环境 npm run tauri dev

（5）全栈开发启动（推荐）

使用项目内置脚本一键启动所有开发服务：

bash # 根目录执行 node scripts/dev-all.mjs

6. 总结

OpenYak 作为本地优先的桌面端 AI 代理工具，核心价值在于兼顾 “数据隐私” 与 “办公效率”，通过本地运行时、多模型适配、多文件解析能力，解决了传统云端 AI 办公工具的账号绑定、数据上云、场景适配不足等问题。其模块化的架构设计和跨平台特性，既满足普通用户开箱即用的需求，也为开发者提供了灵活的二次开发基础，是面向办公场景的轻量化、私有化 AI 工具的优质选择。

* 开源代码仓库：https://github.com/openyak/openyak