GDPuTTY

軟體簡介

GDPuTTY 是一款以 PuTTY 為靈感、但完全用 Python 與網頁技術重新打造的連線終端機軟體。它保留了 PuTTY 在 SSH 老設備上累積二十多年的相容性處理（包含 16 個 SSH bug 旗標、F-key 編碼模式、序列埠 quirk），同時把使用者介面換成以 pywebview 嵌入瀏覽器渲染、由 xterm.js 負責終端機畫面的現代化版面。整支軟體完全不依賴外部 putty.exe，連 .ppk 私鑰也是透過捆綁的 puttygen.exe 動態轉換給 paramiko 使用。

核心特色

特色	說明
原生 paramiko SSH	不依賴 `putty.exe`，所有 SSH 連線都走 paramiko，並補上 PuTTY 的 16 個 `sshbug_*` 相容旗標。
xterm.js 渲染	中文／emoji／真彩色／URL 自動可點，徹底擺脫 PuTTY 老字型的亂碼問題。
Win32 直連序列埠	不走 pyserial、直接 `CreateFile`，搭配 CH340 與 ESP 板的 DTR/RTS quirk 處理。
多協定支援	SSH(1/2)、Telnet、Raw、Rlogin、SUPDUP、Telnet/Serial(RFC 2217)、本機 ConPTY shell。
ESP 韌體燒錄	內建 esptool 等價實作，支援 ESP32 系列與 ESP8266，可選 `FLASH_DEFL` 壓縮上傳。
Claude AI 整合	將 Claude Code CLI 包進側欄，可附帶當前終端輸出給 AI，並讓 AI 直接送指令回終端機。
PuTTY session 匯入	直接讀 Windows registry，將既有 PuTTY 連線一鍵匯入。
雙語介面	預設英文、可切繁體中文；翻譯只走顯示層，內部 key 全部保留中文。

系統需求

項目	內容
作業系統	Windows 10／11（x64）。其他平台未測試。
網路	首次啟動需網路下載 xterm.js（jsDelivr CDN）；後續可離線使用快取版本。
選用元件	Claude Code CLI（AI 助理功能）、PuTTY `puttygen.exe`（`.ppk` 私鑰轉換，內建捆綁）。
資料目錄	—— 連線設定、known_hosts、設定檔均存放於此。

主介面

主畫面由三個區塊構成：頂部工具列、左側連線清單（sidebar）、以及右側的終端機／面板區域（tab strip + terminal area）。下表整理各區塊的主要元素：

區塊	內容
頂部工具列	左方為應用程式 logo 與名稱；右方為全域編碼選擇器、設定按鈕、Claude AI 開關按鈕。
連線清單	顯示所有已儲存的連線；綠點代表線上、紅點離線、灰點未探測；雙擊或點擊圖示按鈕直接開啟。
分頁工具列	顯示已開啟的分頁與每個分頁的協定指示色；額外按鈕包含 ESP 重啟、檔案傳輸、暫停讀取等。
終端機區域	由 xterm.js 渲染；多個分頁共用此區域、以 `visibility` 切換顯示。
狀態列	底部三段式：左為連線狀態與通訊埠、中為當前分頁、右為已開啟分頁數。

連線狀態指示

連線清單左側的圓點顏色說明各 session 的健康度。背景的 HostPinger（model/main.py）每 30 秒做一輪 TCP 探測，序列埠分頁則由 GUI 自己依分頁存活狀態推斷顏色，避免兩個 process 同時開啟同一個 COM port 造成 ACCESS_DENIED。

顏色	意義
綠色	TCP 三向交握成功；序列埠分頁則表示 COM port 已開啟且讀寫正常。
紅色	TCP 連線失敗、port 被防火牆擋下、或序列埠分頁已斷線。
灰色	從未探測過、或 ConPTY 等沒有遠端 host 概念的協定。

新增與管理連線

點擊左側「New Connection」按鈕、頂部分頁列的「＋」、或主畫面中央的「New Connection」皆可開啟連線設定。對話框由五個分頁組成：

分頁	用途
Connection	連線名稱、協定（SSH／Telnet／Raw／Serial／Telnet/Serial／Rlogin／SUPDUP／LocalShell）、Host／Port、字元編碼。
Auth	帳號、密碼、私鑰路徑；`.ppk` 會自動由內建 puttygen 轉換成 OpenSSH 格式。
SSH	IP 版本（auto／4／6）、SSH 協定版本（SSH-2 或 SSH-1 legacy）、壓縮、agent forwarding、keepalive、終端機型別、F-key 編碼、16 個 `sshbug_*` 旗標、KEX／Cipher／MAC／Host Key 候選清單。
Forward	本地／遠端／動態 port forwarding 規則。
Appearance	字型、字級、scrollback 行數、前景／背景／游標顏色、游標樣式與閃爍、行尾轉換規則（`lfhascr`／`crhaslf`）。

SSH 進階選項

SSH 分頁 —— 涵蓋 IP 版本、協定版本、keepalive、F-key 編碼。

SSH 分頁是 GDPuTTY 對 PuTTY 老設備相容性最完整的繼承之處。SSH-2 (modern) 由 paramiko 處理；SSH-1 (legacy) 走 GDPuTTY 自己的 pure-Python SSH-1 客戶端，僅支援 3DES 與密碼認證，專為 Cisco IOS 11.x、F-Secure 1.x、SunOS 5.x 這類老主機保留。Algorithm Compatibility 區塊還可逐項勾選要啟用的 KEX、Cipher、MAC、Host Key 演算法，並提供 16 個 sshbug_* 旗標對照 PuTTY ssh/verstring.c::ssh_detect_bugs 的 quirk。

外觀與終端機色彩

外觀分頁的所有設定都直接套到 xterm.js。預設字型為 Cascadia Mono, Consolas, monospace，預設字級 13、scrollback 5000 行。色彩留空時走深色預設（背景 #0b0e14、前景 #e6e9ef、游標 #4f8cff）。Implicit CR in every LF（lfhascr）與 Implicit LF in every CR（crhaslf）對應 PuTTY 在某些老主機上需要的行尾轉換 quirk。

終端機操作

已連線的 SSH 分頁 —— xterm.js 完整支援 ANSI 顏色與 UTF-8。

連線建立後，xterm.js 會接管整個終端機區域。GDPuTTY 預設啟用滑鼠右鍵「有選取就複製、沒選取就貼上」的便捷操作；Ctrl+C 在有選取時複製、沒選取時送 SIGINT；Ctrl+V 直接從剪貼簿貼上。

分頁工具列按鈕

分頁列右側依當前分頁的協定動態顯示／隱藏工具按鈕。下表整理各按鈕的用途：

按鈕	用途與適用協定
ESP 重啟（圓點）	序列埠分頁專用：脈衝 RTS 重啟 ESP；DTR／RTS 序列遵循 esptool 的 `classic_reset` 規範。
ESP Bootloader（DL）	序列埠分頁專用：讓 ESP 進入下載模式，與下方 ESP 燒錄對話框搭配。
檔案傳輸（資料夾）	SSH／Serial 分頁：彈出 XMODEM／YMODEM／ZMODEM／ESP 韌體選單。
暫停讀取（三角／圓點）	所有分頁：把 reader thread 暫停，避免大量輸出造成 UI 卡頓；恢復後會 drain 已累積的緩衝。
清除（×）	所有分頁：清空 xterm.js 的 scrollback。

字元編碼切換

頂部工具列的「Encoding」下拉可即時切換目前分頁的解碼方式，無須斷線重連。GDPuTTY 用 Python 端的 codecs.getincrementaldecoder 重建解碼器，因此多 byte 序列中途切換編碼也不會殘留 partial state。預設 utf-8，另外提供 big5、gb18030、gbk、shift-jis、euc-kr、cp1252、latin-1 等常見選項，可解決 PuTTY 在中文主機上的亂碼問題。

全域設定

設定對話框 —— 切換語言、選擇 Claude Code 模型、檢視第三方授權。

頂部工具列的齒輪按鈕開啟全域設定。下表整理可調整的項目：

設定項	說明
Language / 語言	`English` 或 `繁體中文`。預設英文，存於 `settings.json`。
Claude Code model	兩段式選擇：先選 family（Opus／Sonnet／Haiku／Custom），再選版本（Latest 或固定版號）。家族 alias 永遠對映到 Claude Code CLI 的最新版本，內建版號則寫死，方便回退。
xhigh (Claude only)	是否在呼叫 Claude 自家模型時帶 `–effort xhigh` 旗標。第三方相容代理（DeepSeek 等）建議關閉。
Bundled puttygen.exe	顯示自動偵測到的 `puttygen.exe` 路徑，用於 `.ppk` 轉 OpenSSH。
Connection data stored	顯示實體位置（`C:/orztrickster/GDPuTTY/sessions.json`）。
Third-Party Licenses	開啟內嵌的第三方授權瀏覽器，列出所有打包依賴的 LICENSE 全文。

DeepSeek 等第三方模型

如果使用者在建立 Claude Code 格式的 env.ANTHROPIC_BASE_URL 與 ANTHROPIC_AUTH_TOKEN，設定對話框會自動顯示 DeepSeek family 選項；選到後 claude_send 會以 –settings 模式走第三方相容代理，原始 Claude 流程不變。檔案不存在時欄位完全隱藏，使用者隨時可在 GUI 切回 Claude 內建模型。

Claude AI 助理

Claude Assistant 面板 —— 對話歷史、可勾選自動附帶終端輸出、特殊 `bash-auto` 區塊可一鍵送到連線分頁。

頂部右側的 ✦ 按鈕會開啟 Claude 助理面板，把它當成一個分頁掛在終端機區域旁邊。它直接呼叫使用者本機安裝的 Claude Code CLI（claude.exe 或 claude.cmd），GDPuTTY 不會把 prompt 直接送到網路上，所有計費、認證、模型選擇都由 Claude Code 處理。

對話流程與終端機整合

預設「Attach current terminal output」勾選為開：每次送訊息時會自動帶上當前連線分頁最近 200 行畫面，AI 因此能看到實際的指令與輸出脈絡。AI 回覆中若包含 “‘bash-auto…“‘ 區塊，GDPuTTY 會通過三層安全防護判斷：

防護層	規則
雙重 block 名單	全域禁用字元（`>`、`>`、`rm`、`sudo` 等破壞性操作）絕不放行。
tentative 偵測	終端機需處於可接受指令的 prompt 狀態；偵測到 pager、密碼輸入欄、TUI 一律降級為手動送出。
白名單	只有不會改變狀態、不會卡輸入的指令（`ls`、`ps`、`cat` 等）才允許自動送出。

通過審核後 AI 指令會自動送到連線分頁、再把輸出送回 AI 解讀，形成「讀畫面 → 提建議 → 執行 → 再讀畫面」的 loop。沒通過的 bash-auto 區塊則降級為手動送出按鈕，並在按鈕旁顯示降級原因。

授權模式

GDPuTTY 採用 prompt-steering 而非硬擋的付費模式：免費版每場對話 10 次訊息，超出後 AI 會被導向「請使用者購買金鑰」的提示語（follow-up 自動回覆不計次）。新增對話會清零計數。持有有效金鑰時則完全跳過配額檢查。金鑰管理沿用 orztrickster_model.Customtkinter_Model().Key_Check 模組，支援綠界（台灣信用卡）與 ETH 加密貨幣兩種付款渠道。

ESP 韌體燒錄

ESP Firmware Flash 對話框 —— 自動偵測檔案類型並推薦 offset、可勾選壓縮上傳。

在序列埠分頁中，點擊頂部分頁列的「資料夾」按鈕、再從選單選擇「ESP firmware flash」即可開啟此對話框。GDPuTTY 內建一份 esptool 等價實作（model/detai_model/esp_loader.py），無須額外安裝 esptool.py。

對話框欄位

欄位	用途
Target chip	ESP32／ESP32-S2／ESP32-S3／ESP32-C3／ESP32-C6／ESP8266。選 `auto` 時由 `detect_chip` 自動辨識。
Connection	`usb-serial-jtag` 或 `uart`。前者跳過 hard reset 序列，適用內建 USB-Serial-JTAG 的 ESP32 系列。
Files to flash	拖檔或按「＋ Add files」加入 `.bin` 檔；GDPuTTY 會依檔名（`bootloader`／`partition`／其他）推薦 offset。
Compress upload	啟用 `FLASH_DEFL` 壓縮命令，傳輸時間通常可減少 30%–60%；需要 stub loader 載入成功才可用。
Hard-reset after flash	燒完後脈衝 RTS 重啟板子，避免使用者手動按 reset。

底層細節

特性	說明
CH340 reset quirk	Win32 + classic auto-reset 板的 reset 結束狀態必須留在 `(DTR=T, RTS=T)`，繞過 CH340 的 `SetCommState` re-pulse。
Stub loader	MEM_END 後必須 loop 跳過非 OHAI packet，否則 `_is_stub=False` 會讓壓縮上傳失效。
壓縮上傳	`FLASH_DEFL_BEGIN` 第一個欄位是 raw size（解壓後總長），不是 sector-aligned 的 erase size。
晶片識別	透過 magic value table 比對；參考 esptool `CHIP_DEFS`。

從 PuTTY 匯入既有連線

Import Connections from PuTTY —— 直接讀 Windows registry、可逐筆勾選。

如果機器上已經有 PuTTY 並存了一堆連線，可以直接從側欄底部的「Import from PuTTY」按鈕呼叫此對話框。GDPuTTY 走 Windows registry 路徑列出每筆 session，欄位包含 HostName、PortNumber、Protocol、UserName、SerialLine 等。

匯入流程完全唯讀，不需要 putty.exe 二進位檔，也不會修改原 PuTTY 設定。匯入後的 session 預設保留原名稱，序列埠連線會自動轉成 GDPuTTY 的 serial 協定並沿用 baud rate；SSH／Telnet／Raw 則直接以對應協定建立新 session。

第三方授權

Third-Party Licenses —— 動態掃描 dist-info 與 PuTTY 原始碼目錄。

設定對話框的「Third-Party Licenses」按鈕會打開此面板，列出 GDPuTTY 散佈時所依賴的全部第三方授權。為了避免散佈合規漏列，GDPuTTY 不採用硬寫的清單，而是動態掃描兩個目錄：

來源目錄	內容
	Python 套件的 wheel metadata；包含 LICENSE／LICENCE／NOTICE 與 `licenses/` 子目錄中的多檔授權（例如 cryptography 的 Apache + BSD 雙授權）。
	PuTTY 原始碼樹的授權；版本號從 `version.h` 的 `#define RELEASE` 抓取。

點開每一筆條目可看到該套件的完整授權全文。新增依賴時不需要改任何清單，重新打包後此面板會自動列出新增的條目。