這是什麼
stock-agent 是一支安裝在你自己電腦上執行的小程式，負責連線券商（富邦 Neo SDK／台新 Nova 等）取得即時盤中行情， 或使用內建的模擬行情，並整理成一個本機網頁「盤中工作台」，用瀏覽器打開 http://127.0.0.1:5300 即可查看。
你也可以選擇把這台 Agent 與雲端主系統「配對」，讓雲端能看到它的在線狀態，並可統一下發要監看的股票清單。
開始之前：系統需求
| 作業系統 | Windows 10 / 11（64 位元） |
| Node.js | 必須先安裝 Node.js 20 以上版本，安裝完成後打開「命令提示字元」輸入 node -v 能看到版本號即代表安裝成功。 |
| 網路 | 要接真實券商行情才需要對外網路；只用模擬行情不需要 |
| 權限 | 一般操作不需要系統管理員權限，「安裝為背景服務」這一步才需要 |
node，即使只是要看「模擬行情」也無法啟動， 畫面會出現「找不到 node 執行環境」的錯誤。請先到 Node.js 官方網站下載 LTS 版本並完成安裝。 下載與解壓
- 前往 Agent 下載頁 ，下載 Windows 版壓縮檔（檔名類似
stock-agent-<版本號>-windows-amd64.zip）。 - 解壓縮到一個方便管理的資料夾，例如
C:\Tools\StockAgent\。 - 請保持解壓後的資料夾結構完整（
stock-agent.exe、agent\ui、sidecars需在同一層），不要單獨搬動主程式檔案。
第一次啟動（前景測試）
- 在解壓的資料夾內開啟 PowerShell（按住 Shift 右鍵 → 「在此處開啟 PowerShell 視窗」）。
- 執行：
.\stock-agent.exe run - 終端機會顯示監聽網址與登入用的
first-run token，請保留這個視窗不要關閉。 - 瀏覽器開啟
http://127.0.0.1:5300，貼上顯示的 token 登入； 也可以直接使用網址列附帶 token 的一鍵登入連結，建議加入書籤。
首次啟動會自動在 %USERPROFILE%\.stock-agent\ 建立設定與資料目錄， 所有帳密、憑證與行情紀錄都存放於此，且已加密保護。
選擇行情來源
登入後點右上角齒輪圖示進入設定畫面。
先用模擬行情測試
選擇「模擬行情（simulator）」即可直接使用，不需帳號或憑證，適合第一次確認整體流程是否正常。
接上真實券商（富邦／台新）
需通過「就緒檢查清單」的所有項目才能啟用：
| 券商 SDK 模組 | 是否已上傳並安裝對應券商的 SDK |
| 券商帳號與密碼 | 是否已填寫 |
| 憑證檔 | 是否已上傳且檔案存在 |
| 憑證密碼 | 是否已填寫 |
- 上傳券商 SDK 壓縮檔（
.zip或.tgz/.tar.gz，上限 512MB）。 SDK 需自行向券商取得，不隨程式散布。 - 填寫帳號／身分證字號、登入密碼、API Key（若券商要求）。
- 上傳憑證檔，支援
.pfx/.p12/.pem/.crt/.cer。 - 填寫憑證密碼。
- 按「測試登入」確認可連上券商。
- 全部項目變成 ✓ 後，按「儲存並套用」。
.whl，與實戰驗證過的參考方案一致， 支援 API Key／憑證等三種登入模式），本機需安裝 Python 3.8+ 並加入 PATH， 首次登入會自動建立環境安裝。不想裝 Python 可切換 Node 版備援（FUBON_BACKEND=node）。 .tgz）與 Python 版（.whl）兩種， 程式預設使用 Node 版，不需要安裝任何額外軟體——上傳 tgz 檔後首次登入會自動安裝。 只有進階使用者改用 Python 版備援模式時，才需要本機另外安裝 Python 3.8+。 與雲端主系統配對（選用）
若想讓雲端主系統看到這台 Agent 的在線狀態，或想從雲端統一下發監看清單：
方式一：手動貼上
- 在雲端主系統「設定」頁的「Local Agent 配對」區塊按「建立 Token」，輸入這台電腦的代稱。
- 複製產生的配對碼（僅顯示一次）。
- 回到本機 Agent 設定畫面的「主系統 Uplink」欄位，填入 Uplink URL 與配對碼並儲存。
方式二：匯出／匯入配對檔（較不易打錯字）
- 在雲端主系統「設定」頁按「匯出設定」，下載
stock-agent-pairing.json。 - 回到本機 Agent 設定畫面的「匯入設定 / 配對檔」上傳該檔案，欄位會自動帶入並儲存。
配對完成後，雲端主系統每 15 秒更新一次這台 Agent 的在線與就緒狀態。
設定要監看的股票
在本機控制台設定畫面的「訂閱清單」欄位，用逗號分隔輸入股票代號（例如 2330,2317,2454）。 若已完成雲端配對，也可以直接由雲端推送清單，不需手動輸入。
安裝為 Windows 背景服務
測試沒問題後，建議安裝為服務，開機自動啟動，不需每次手動開視窗。
- 關閉前景測試視窗。
- 以系統管理員身分開啟 PowerShell（開始選單搜尋「PowerShell」，右鍵「以系統管理員身分執行」）。
- 進入程式所在資料夾，依序執行：
.\stock-agent.exe service install .\stock-agent.exe service start - 確認狀態：
顯示「● 運作中」即代表成功。.\stock-agent.exe service status
service stop | 停止服務 |
service start | 啟動服務 |
service status | 查看目前狀態 |
service uninstall | 解除安裝服務 |
service uninstall → service install → service start。 服務模式沒有終端機視窗可看紀錄，執行紀錄會寫到 %USERPROFILE%\.stock-agent\agent.log。
查看券商帳號庫存部位
登入本機控制台、且已成功連上行情來源（模擬或真實券商皆可）後，畫面下方會顯示「庫存部位」面板， 列出目前登入帳號的持股：代號、市場別、庫存股數、均價。
- 面板每 15 秒自動重新整理一次，也可以按「重新整理」立即刷新。
- 目前模擬行情、富邦、台新支援庫存查詢， 群益／凱基仍在開發中，查詢會顯示尚未支援。
- 庫存資料僅在本機查詢與顯示，不會上傳到雲端主系統。
查看行情紀錄與檔案
盤中行情原始資料依日期與股票代號落地儲存在 %USERPROFILE%\.stock-agent\data\<日期>\<股票代號>.jsonl， 也可以直接在本機控制台網頁的「檔案」頁面瀏覽與下載。
安全性維護：登入 Token 輪替
本機控制台的登入 Token 等同於「密碼」。若懷疑外流，可在設定畫面按「輪替 Token」：
- 舊 Token 與舊的一鍵登入連結立即失效。
- 除了目前這個瀏覽器，其他已登入裝置也會一併登出。
- 輪替後請重新複製新的一鍵登入連結並更新書籤。
常見問題
執行時出現「找不到 node 執行環境」？
代表未安裝 Node.js 或未加入系統 PATH。請安裝 Node.js 20+ 後，開一個新的終端機視窗再試一次。
安裝服務時顯示「安裝失敗」？
請確認是以「系統管理員身分」開啟的 PowerShell／命令提示字元，一般權限無法安裝 Windows 服務。
服務裝好了，但行情來源啟動失敗，前景模式卻可以？
通常是先裝服務、後裝 Node.js（或後加入 PATH）造成的。請重新 service uninstall 再 install、start 一次。
上傳 SDK 顯示「壓縮檔內找不到 package.json / index.js」？
代表壓縮檔內容不是有效的 SDK 模組。請確認上傳的是券商提供的原始 SDK 壓縮檔，勿自行改動壓縮包結構。
憑證檔要用什麼格式？
支援 .pfx、.p12、.pem、.crt、.cer，依券商提供的格式選擇即可。
行情或帳密資料會不會被上傳到雲端？
不會。只存在你自己電腦的 %USERPROFILE%\.stock-agent\ 目錄下。上傳到雲端的僅有簡短在線狀態心跳，不含行情內容或密碼明文。
庫存部位面板顯示「查詢失敗」？
常見原因：行情來源尚未連線成功；目前券商尚未支援庫存查詢（模擬行情、富邦、台新已支援）； 或券商連線暫時中斷，稍待自動重連後再按「重新整理」。