使用文档

安装

源有三种安装方式，选一种就行。

桌面版（推荐）

下载安装包后一路下一步。装完会在桌面和开始菜单创建快捷方式，首次启动需要 20 到 40 秒（要初始化数据库、加载模型配置）。

支持 Windows 10 以上。macOS 和 Linux 目前需要用源码方式安装。

Docker

适合装在公司内网服务器上，让整个团队连进来用。

docker run -d --name yuan \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config:/app/config \
  --restart unless-stopped \
  yuan-assistant:latest

启动后打开 http://服务器地址:8080。

data/ 放数据库、上传的文件、日志；config/ 放配置文件。这两个目录一定要挂出来，否则容器重建时数据会丢。

源码

需要 Python 3.10 以上。

git clone <你的来源> yuan && cd yuan
pip install -r requirements.txt
python main.py web

前端如果要重新构建：

cd frontend && npm install && npm run build

系统要求

只用云端模型（OpenAI、Claude、Gemini）的话不需要显卡。要完全离线跑本地模型才需要，没显卡也能跑，只是慢很多。

首次启动

首次启动时，系统会生成一组管理员账号密码，只显示一次。

桌面版会直接弹窗显示。服务器版本会打印在终端的启动信息里：

============================================
  管理员账号已创建
  账号：admin
  密码：xK9mP2vL8qR4nW7t
  请立即登录并修改密码
============================================

登录后第一件事：到 设置 → 账号 改成自己的密码。

接下来配置模型

没配置模型的话源没法回话。有两条路：

用云端模型 — 到 设置 → 模型，粘贴 API Key。支持 OpenAI、Anthropic、Google。Key 会加密后存进数据库，不会写进配置文件。

用本地模型 — 到 设置 → 推理引擎，点「一键安装 Ollama」。详见本地推理。

两种可以同时配置，之后在对话框上方切换。

对话

主界面左边是对话列表，中间是对话区，右边是状态面板。

模式

左上角有三个模式可切换，会影响回答风格和可用的工具：

思考深度

对话框旁边的设置可以调整思考深度：

• ⚡ 快速 — 直接回答，适合简单问题
• ⚖️ 平衡 — 默认值
• 🧐 深度 — 会先想过再回答，适合复杂问题，慢一些也贵一些
• 🎨 创意 — 发散、头脑风暴

只有支持推理的模型（o 系列、Claude、Gemini 等）会实际生效，其他模型会忽略这个设置。

附加文件

可以直接拖进对话框，或点回形针。支持 PDF、Word、Excel、PowerPoint、纯文本、代码文件、图片。

单个文件上限 25 MB。图片会用视觉模型分析，文档会抽取文字后放进上下文。

屏幕上下文

对话框旁边的眼睛图标打开后，发消息时会一并告诉源你当前在用哪个程序、窗口标题是什么。

问「这个报错是什么意思」的时候不用再解释你在哪个界面。关掉就不会采集。

语音

语音输入

按 Alt+V，或点对话框旁边的麦克风。说完后会自动识别成文字填进输入框，你可以先改再发。

有两种识别方式，在麦克风旁边切换：

• 本地识别 — 浏览器内置的语音识别，或本地的 faster-whisper。不会上传音频。
• 云端识别 — 发到 Whisper API，准确度更高。

首次使用本地识别会下载语音模型（约 150 MB），界面上会显示进度。

实时语音对话

按两下 Alt+V 进入实时对话模式。这是双向语音，说完就回，讲到一半可以直接打断它。

适合开会、开车、手上在忙的时候。用的是云端实时语音服务，所以这个模式下音频会离开你的机器。要完全离线就用上面的本地识别。

工具与自动化

源不只是回话，它会自己用工具把事情做完。你说「把这个文件夹的 CSV 合并后画成图表发给 Kevin」，它会自己拆成读文件、运算、生成图、发邮件几步执行。

执行工具时对话里会出现灰色小标签，显示它正在做什么。

有哪些工具

共 43 个。实际可用数量看你的授权版本。

权限与确认

危险操作（删文件、跑系统命令、写入文件）默认需要你点确认才会执行。可以在 设置 → 权限 改成自动批准，但不建议。

文件操作限制在沙箱目录和你明确授权的路径内，源碰不到授权范围外的文件。

浏览器自动化

源可以实际操作浏览器：

你：去 example.com 登录，账号 [email protected]，然后把订单页的数据抓下来

它会依次执行打开页面、填表单、点按钮、提取内容。浏览器 session 在同一段对话里会保持登录状态。

本地推理

本地推理让数据完全不离开你的机器。适合有合规要求或处理敏感数据的场景。

安装

到 设置 → 推理引擎，点「一键安装 Ollama」。系统会检测你的显存，推荐合适的模型大小：

下载过程会显示进度。装完后在对话框上方就能选到本地模型。

支持 37 个模型系列，包含 Qwen、Llama、Gemma、DeepSeek、Mistral、Phi。

隐私模式

设置 → 隐私 里可以开启隐私模式。开启后系统会强制只走本地模型，就算你误选了云端模型也不会发出去。

vLLM

如果有多张显卡，可以改用 vLLM 获得更好的吞吐。在 设置 → 推理引擎 选择 vLLM 并指定模型即可。vLLM 需要显卡，不支持纯 CPU。

通讯平台

源可以挂到通讯软件上，让同事或客户直接对话。所有平台共用同一份记忆和知识库。

支持飞书、Telegram、Discord、LINE 官方账号。

它们的运行方式不一样，这会影响你要开几个进程、要不要公网地址：

飞书

到飞书开放平台创建企业自建应用：

feishu:
  app_id: "cli_xxxx"
  app_secret: "你的 secret"
  verification_token: "事件订阅验证 token"

事件订阅地址填 https://你的域名/api/feishu/webhook，订阅 im.message.receive_v1 事件。这是唯一挂在 web 主进程下的平台，不用另外开进程。

Telegram

找 BotFather 申请 bot 拿到 token：

telegram:
  token: "你的 token"

python main.py telegram

Telegram 用主动轮询，不需要公网地址，纯内网也能跑。

Discord

到 Discord Developer Portal 创建应用和 bot，开启 Message Content Intent：

discord:
  token: "你的 bot token"

python main.py discord

Discord 走长连接，同样不需要公网地址。

LINE 官方账号

面向海外客户时常用。到 LINE Developers 创建 Messaging API channel：

line:
  channel_access_token: "你的 token"
  channel_secret: "你的 secret"
  webhook_port: 8443

python main.py line

Webhook 地址填 https://你的域名:8443/webhook。

改完配置要重启对应的进程才生效。要同时开多个平台，就各自开一个进程，它们共用同一个数据库。

项目与文件

项目让你把一组相关的对话、文件和规则绑在一起。

创建项目

侧边栏的项目图标 → 新建项目。填名称和说明。

关联文件夹

在项目里可以关联本机文件夹。关联后源会扫描里面的文件结构（会自动跳过 .git、node_modules、__pycache__ 这类目录，也会读 .gitignore），之后在这个项目里对话时就知道有哪些文件。

桌面版会弹出系统的文件夹选择窗口。

工作约定

项目里可以写「工作约定」，就是这个项目专属的规则。例如：

回复一律用简体中文。
代码注释用英文。
提到金额时一律标注币种。

这些规则只在该项目的对话里生效。

项目记忆

项目积累的知识会存成项目记忆，跟着项目走。切到别的项目不会互相干扰。

设置

模型

管理各家 API Key 和默认模型。Key 加密存在数据库里，界面上只显示末四位，需要时可以点眼睛图标查看。

可以设置主模型和备用模型。主模型失败时会自动切到备用。

外观与语言

界面语言支持繁体中文、简体中文、英文、日文。深色和浅色主题。

快捷键

桌面版的全局快捷键，在任何程序里都能用：

个人 API 令牌

要从自己的程序调用源，可以在 设置 → 令牌 创建个人访问令牌。创建时会显示一次完整的令牌，之后只看得到前缀。

备份

设置 → 备份 可以手动创建备份，或配置自动备份。备份包含数据库和上传的文件。也可以导出成 JSON 带走全部数据。

授权

版本差异

激活

到 设置 → 授权，会看到这台机器的设备识别码（HWID）。购买时把这串码提供给我们，我们会发一组授权码给你。

拿到授权码后粘进同一页的输入框点激活即可。

一组授权码绑定一台机器。要换机器的话联系我们解绑。

授权状态

授权会定期跟授权服务器确认。断网情况下有 1 天宽限期，超过就会停用。功能或到期日有调整时，会在下次确认时自动更新，不需要重新激活。

企业部署

这一节是给运维人员看的。

PostgreSQL

默认用 SQLite，单机够用。要多台机器共享数据就改 PostgreSQL：

database:
  url: "postgresql://user:password@db-host:5432/yuan"
  pool_size: 20

改完重启，schema 会自动创建。

Redis

多台机器需要共享缓存和限流：

cache:
  backend: "redis"
  redis_url: "redis://redis-host:6379/0"

不配置的话用内存缓存，单机没问题，多台会各算各的。

后台任务队列

耗时任务可以丢给 Celery worker 处理，避免卡住 web 服务：

task_queue:
  backend: "celery"
  broker_url: "redis://redis-host:6379/1"

worker 用这个命令启动：

celery -A worker worker --loglevel=info

SSO 单点登录

支持 OIDC（微信、QQ、Google、Microsoft Entra ID）和 SAML 2.0。

sso:
  oidc:
    wechat:
      client_id: "..."
      client_secret: "..."
    google:
      client_id: "..."
      client_secret: "..."
  saml:
    idp_entity_id: "..."
    idp_sso_url: "..."
    idp_x509_cert: "..."

回调地址填 https://你的域名/api/sso/{provider}/callback。SAML 的 SP metadata 在 https://你的域名/api/sso/saml/metadata。

访问控制

security:
  ip_whitelist: ["10.0.0.0/8", "192.168.1.0/24"]
  ip_blacklist: []
  max_sessions: 5
  login_lockout_attempts: 5
  login_lockout_minutes: 15

ip_whitelist 留空表示不限制。支持 CIDR 格式。

>

权限分四级：访客、普通、高级、管理员。每一级能用的工具不同，可在 设置 → 权限 调整。

审计与合规

所有操作都会记录，包含操作者、动作、目标、IP、时间。管理员可在后台查看。

合规报告可导出：

GET /api/admin/compliance/report?start=<unix>&end=<unix>&format=csv

需要管理员权限。内容包含审计日志、登录记录、用量统计。

数据删除：后台可以一键删除指定用户的所有数据，包含对话、记忆、文档、上传文件。

Kubernetes

deploy/k8s/ 有现成的部署文件，包含 Deployment（3 副本）、Service、Ingress、HPA（CPU 70% 触发，2 到 10 副本）。

kubectl apply -f deploy/k8s/

数据库连接串和密钥放在 Secret 里，配置文件用 ConfigMap 挂载。

加密

配置文件里的敏感字段（API Key、token、密码）会自动加密，加密后的值以 ENC:: 开头。密钥绑定机器，换机器需要重新输入。

数据库可选择加密。安装 pysqlcipher3 后系统会自动检测并启用，现有的未加密数据库会自动迁移。

API 参考

源的 API 跑在你自己的机器上，不是我们的服务器。Base URL 就是你的安装地址，例如 http://localhost:8080 或 https://yuan.你的公司.com。

适合把源接进公司现有系统：内部工单、CRM、定时脚本、自己写的前端。

所有端点同时挂在 /api 和 /api/v1 两个前缀下，内容一样。下面统一用 /api。

认证

到 设置 → 令牌 创建个人访问令牌，创建时会返回一次完整的令牌：

{ "token": "sk-asst-xxxxxxxxxxxxxxxxxxxx", "name": "我的集成" }

之后每个请求带上这个 header：

Authorization: Bearer sk-asst-xxxxxxxxxxxxxxxxxxxx

权限跟着账号走，不是跟着令牌 —— 把账号降权，它名下所有令牌一起降权。在 设置 → 令牌 删掉某个令牌，它会立刻失效。

还有一条路：桌面版在本机（127.0.0.1）发出的请求会自动以本机用户身份通过，不用带 header。所以在同一台机器上写脚本，可以直接调用，不必先建令牌。

先跑一个看看

最短的完整例子 —— 发一句话，拿一句回复：

curl -X POST http://localhost:8080/api/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "把上周的销售数字整理一下", "stream": false}'

返回：

{ "conversation_id": 42, "content": "上周总销售额为 ..." }

对话

POST /api/chat 是主要的对话端点。

stream: true 时返回 text/event-stream，每条事件是一行 data: 加一个 JSON：

管理对话

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/conversations?search=销售&limit=20"

文档

curl -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]" \
  http://localhost:8080/api/documents/upload

上传后会自动切块建索引，之后对话时可以被引用。

语音与图片

系统

/api/health 不需要认证，适合给负载均衡或监控系统做探测。

WebSocket

界面本身走 WebSocket，因为要实时推送工具执行状态。要自己写交互式前端才需要用到，一般集成用上面的 /api/chat 就够了。

浏览器客户端必须先用个人令牌或 JWT 换取一个短时有效、仅可使用一次的 WebSocket ticket。凭据只能放在 HTTP Authorization header 中，绝对不要放进 URL。

POST http://localhost:8080/api/ws-ticket
Authorization: Bearer <你的令牌>

返回的 ticket 只可用于一次连接尝试。每次重新连接前都要换取新的 ticket：

ws://localhost:8080/api/ws?ticket=<一次性 ticket>

非浏览器客户端如果能在 WebSocket upgrade 请求中设置 Authorization: Bearer header，也可以直接使用该 header，不必换取 ticket。

连上后必须先发一条消息，服务端会把第一条当作 init frame。这个 frame 用来设置 session，不负责连接认证：

{ "type": "init" }

之后才发实际内容：

{ "type": "chat", "message": "...", "conversation_id": 42, "mode": "work" }

服务端返回的 type 包括 typing、tool_call、tool_result、chunk、done、error、conversation_created。

错误格式

错误一律返回这个结构：

{
  "error": "AUTH_1002",
  "message": "令牌已过期"
}

代码有前缀，分段如下：

用程序判断时请比对 error 代码，message 的文字会随语言变化。

限流

超过限制会返回 429。每日对话条数依授权版本而定，见授权。

故障排查

启动失败

先看日志，位置在 data/logs/。桌面版可以从托盘菜单打开日志目录。

常见原因：

端口被占用 — 默认 8080。改 config.yaml 里的 web.port，或关掉占用的程序。

数据库被锁 — 有另一个实例还在跑。桌面版会自动检测并切到已有窗口；服务器版本要先确认旧进程已退出。

模型未配置 — 界面会提示，到设置里填 API Key 或装本地模型。

回复很慢

• 用本地模型的话，看 设置 → 推理引擎 里的显存占用。如果模型太大塞不进显存，会退回 CPU 运算，速度差很多，换小一点的模型。
• 思考深度设成「深度」会明显变慢，日常用「平衡」就好。
• 对话很长的时候，上下文变大也会变慢。开新对话会快很多。

语音没反应

• 检查浏览器或系统有没有给麦克风权限
• 本地识别首次要下载模型，等进度条跑完
• 桌面版如果 Alt+V 没反应，可能是被其他程序抢了快捷键

通讯平台收不到消息

• Webhook 地址必须是 HTTPS，而且要能从外网访问到
• 检查 data/logs/ 里有没有收到请求的记录
• Telegram 可以先用 polling 模式测试，不需要公网地址
• 国内环境注意机器能否访问对应的境外服务

授权失效

• 确认机器能连到授权服务器
• 换过硬件（主板、网卡、硬盘）会导致设备识别码改变，需要重新绑定
• 离线超过 1 天会停用，联网后会自动恢复

还是解决不了

把 data/logs/ 里最近的日志发给我们，附上你做了什么操作、预期什么结果、实际发生什么。