使用文件

安裝

源有三種安裝方式，選一種就好。

桌面版（建議）

下載安裝檔後一路下一步。安裝完會在桌面和開始選單建立捷徑，第一次啟動需要 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）的話不需要 GPU。要完全離線跑本地模型才需要顯卡，沒有顯卡也能跑，只是慢很多。

第一次啟動

第一次啟動時，系統會產生一組管理員帳號密碼，只會顯示一次。

桌面版會直接跳出視窗顯示。伺服器版本會印在終端機的啟動訊息裡，長這樣：

============================================
  管理員帳號已建立
  帳號：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。

通訊平台

源可以掛到通訊軟體上，讓客戶或同事直接對話。所有平台共用同一份記憶和知識庫。

支援 LINE 官方帳號、Telegram、Discord、飛書。

先看一下它們的執行方式不一樣，這會影響你要開幾個行程、要不要公開網址：

飛書

到飛書開放平台建立企業自建應用：

feishu:
  app_id: "cli_xxxx"
  app_secret: "你的 secret"
  verification_token: "事件訂閱驗證 token"

事件訂閱網址設成 https://你的網域/api/feishu/webhook，訂閱 im.message.receive_v1 事件。這是唯一掛在 web 主程式底下的平台，不用另外開行程。

LINE 官方帳號

1. 到 LINE Developers 建立 Messaging API channel
2. 取得 Channel Access Token 和 Channel Secret
3. 在 config.yaml 填入：

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

1. 另外開一個行程：

python main.py line

1. 把 Webhook URL 設成 https://你的網域:8443/webhook

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 走長連線，一樣不需要公開網址。

改完設定要重啟對應的行程才會生效。要同時開多個平台，就各自開一個行程，它們共用同一個資料庫。

專案與檔案

專案讓你把一組相關的對話、檔案和規則綁在一起。

建立專案

側邊欄的專案圖示 → 新增專案。填名稱和說明。

連結資料夾

在專案裡可以連結本機資料夾。連結後源會掃描裡面的檔案結構（會自動略過 .git、node_modules、__pycache__ 這類目錄，也會讀 .gitignore），之後在這個專案裡對話時就知道有哪些檔案。

桌面版會跳出系統的資料夾選擇視窗。

工作協議

專案裡可以寫「工作協議」，就是這個專案專屬的規則。例如：

回覆一律用繁體中文。
程式碼註解用英文。
提到金額時一律標示幣別。

這些規則只在該專案的對話裡生效。

專案記憶

專案累積的知識會存成專案記憶，跟著專案走。切換到別的專案不會互相干擾。

設定

模型

管理各家 API Key 和預設模型。Key 用加密方式存在資料庫，介面上只顯示末四碼，需要時可以按眼睛圖示查看。

可以設定主要模型和備援模型。主要模型失敗時會自動切到備援。

外觀與語言

介面語言支援繁體中文、簡體中文、英文、日文。深色和淺色主題。

快捷鍵

桌面版的全域快捷鍵，在任何程式裡都能用：

個人 API Token

要從自己的程式呼叫源的話，可以在 設定 → Token 建立個人存取權杖。建立時會顯示一次完整的 token，之後只看得到前綴。

備份

設定 → 備份 可以手動建立備份，或設定自動備份。備份包含資料庫和上傳的檔案。也可以匯出成 JSON 帶走全部資料。

授權

版本差異

啟用

到 設定 → 授權，會看到這台機器的裝置識別碼（HWID）。購買時把這串碼提供給我們，我們會發一組授權碼給你。

拿到授權碼後貼進同一頁的輸入框按啟用即可。

一組授權碼綁定一台機器。要換機器的話聯繫我們解除綁定。

授權狀態

授權會定期跟授權伺服器確認。斷網的情況下有 1 天寬限期，超過就會停用。功能或到期日有調整時，會在下次確認時自動更新，不需要重新啟用。

企業部署

這一節是給 IT 人員看的。

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（Google、Microsoft Entra ID、微信、QQ）和 SAML 2.0（Okta、OneLogin 等）。

sso:
  oidc:
    google:
      client_id: "..."
      client_secret: "..."
    azure:
      client_id: "..."
      client_secret: "..."
      tenant: "你的 tenant id"
  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

需要管理員權限。內容包含稽核日誌、登入紀錄、用量統計。

GDPR 刪除：後台可以一鍵刪除指定使用者的所有資料，包含對話、記憶、文件、上傳檔案。

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 建立個人存取權杖，建立時會回傳一次完整的 token：

{ "token": "sk-asst-xxxxxxxxxxxxxxxxxxxx", "name": "我的整合" }

之後每個請求帶上這個 header：

Authorization: Bearer sk-asst-xxxxxxxxxxxxxxxxxxxx

權限跟著帳號走，不是跟著 token —— 把帳號降權，它名下所有 token 一起降權。在 設定 → Token 刪掉某個 token，它會立刻失效。

還有一條路：桌面版在本機（127.0.0.1）發出的請求會自動以本機使用者身分通過，不用帶 header。所以在同一台機器上寫腳本，可以直接呼叫不必先建 token。

先跑一個看看

最短的完整例子 —— 送一句話，拿一句回覆：

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 就夠了。

瀏覽器 client 必須先用個人 token 或 JWT 換取一個短時有效、僅可使用一次的 WebSocket ticket。憑證只能放在 HTTP Authorization header 中，絕對不要放進 URL。

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

回傳的 ticket 只可用於一次連線嘗試。每次重新連線前都要換取新的 ticket：

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

非瀏覽器 client 如果能在 WebSocket upgrade request 中設定 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": "Token 已過期"
}

代碼有前綴，分段如下：

用程式判斷時請比對 error 代碼，message 的文字會依語言變動。

速率限制

超過限制會回 429。每日對話則數依授權版本而定，見授權。

疑難排解

啟動失敗

先看日誌，位置在 data/logs/。桌面版可以從托盤選單開啟日誌資料夾。

常見原因：

連接埠被佔用 — 預設 8080。改 config.yaml 裡的 web.port，或關掉佔用的程式。

資料庫鎖定 — 有另一個實例還在跑。桌面版會自動偵測並切換到既有視窗；伺服器版本要先確認舊 process 已結束。

模型未設定 — 畫面會提示，到設定裡填 API Key 或裝本地模型。

回話很慢

• 用本地模型的話，看 設定 → 推論引擎 裡的 GPU 使用率。如果模型太大塞不進顯卡記憶體，會退回 CPU 運算，速度差很多，換小一點的模型。
• 思考深度設在「深度」會明顯變慢，日常用「平衡」就好。
• 對話很長的時候，上下文變大也會變慢。開新對話會快很多。

語音沒反應

• 檢查瀏覽器或系統有沒有給麥克風權限
• 本地辨識第一次要下載模型，等進度條跑完
• 桌面版如果 Alt+V 沒反應，可能是被其他程式搶走快捷鍵

通訊平台收不到訊息

• Webhook 網址必須是 HTTPS，而且要能從外網連到
• 檢查 data/logs/ 裡有沒有收到請求的紀錄
• Telegram 可以先改用 polling 模式測試，不需要公開網址

授權失效

• 確認機器能連到授權伺服器
• 換過硬體（主機板、網卡、硬碟）會導致裝置識別碼改變，需要重新綁定
• 離線超過 1 天會停用，連上網後會自動恢復

還是解決不了

把 data/logs/ 裡最近的日誌寄給我們，附上你做了什麼操作、預期什麼結果、實際發生什麼。