{
 "byKey": {
  "cover": [
   {"say":"大家好,歡迎回到 Linux A I 助理開發實戰。這一章是 Python 開發基礎,我們要把虛擬環境建好、學會管理套件、複習幾個常用語法,最後學會怎麼安全地執行系統指令。","item":0}
  ],
  "安裝 Python 與建立 venv 虛擬環境#1": [
   {"say":"先說明一下,為什麼這門課選擇用 Python。","item":0},
   {"say":"因為 Linux 維運常用的函式庫,還有各家 L L M 的官方 S D K,都是以 Python 為主要支援的語言,而且 Ubuntu 本來就內建 Python 三。","item":1},
   {"say":"這門課用的就是 Python 三。Ubuntu 二二點零四預設是三點一零,二四點零四預設是三點一二,兩個版本都可以用。","item":1}
  ],
  "安裝 Python 與建立 venv 虛擬環境#2": [
   {"say":"我們先檢查一下,電腦裡的 Python 有沒有裝好。","item":0},
   {"say":"畫面上的指令,第一行是查看 Python 三的版本。後面兩行是先更新套件清單,再用 A P T 安裝 Python 三、虛擬環境模組,還有 pip。","item":1},
   {"say":"如果沒有安裝虛擬環境那個套件,等一下建立虛擬環境的時候,會跳出一個錯誤訊息,這時候照著提示去安裝就可以了。","item":2}
  ],
  "安裝 Python 與建立 venv 虛擬環境#3": [
   {"say":"那為什麼一定要用虛擬環境呢?","item":0},
   {"say":"因為系統裡的 Python,是給作業系統自己的工具用的。如果你用 sudo 加 pip,把套件直接灌進系統,可能會造成版本衝突,甚至把系統工具弄壞。","item":1},
   {"say":"Ubuntu 二四點零四在這方面更嚴格,直接用 pip 安裝,會看到一個說環境是由外部管理的錯誤。正確的做法是,每個專案都有自己的一個虛擬環境。","item":1}
  ],
  "安裝 Python 與建立 venv 虛擬環境#4": [
   {"say":"好,我們來建立並且啟用虛擬環境。","item":0},
   {"say":"步驟是這樣。先進入專案目錄,用 Python 三的 V E N V 模組,建立一個叫做點 V E N V 的目錄,再用 source 指令把它啟用。接著用 which python 確認一下,路徑應該要指向專案裡的點 V E N V 目錄。","item":1},
   {"say":"啟用成功之後,提示字元的最前面,會多出括號包起來的點 V E N V。要離開虛擬環境的時候,輸入 deactivate 就可以了。","item":2}
  ],
  "安裝 Python 與建立 venv 虛擬環境#5": [
   {"say":"關於虛擬環境,有三個重要的觀念。","item":0},
   {"say":"第一,點 V E N V 這個目錄不要提交進 git,我們在第一章的忽略清單裡已經排除它了。","item":1},
   {"say":"第二,別人拿到專案的時候,只要重新建立虛擬環境,再照著套件清單安裝一次,就能重現一樣的環境。","item":2},
   {"say":"第三,之後用 system D 或是 cron 來執行的時候,要直接指定虛擬環境裡面 Python 的完整路徑,因為它們不會幫你做啟用這個動作。這個第十四章會用到。","item":3}
  ],
  "安裝 Python 與建立 venv 虛擬環境#6": [
   {"say":"虛擬環境最常遇到的錯誤有四個。","item":0},
   {"say":"第一,忘記啟用就直接安裝套件,結果裝到別的地方,或是被系統擋下來。可以用 which python 和 which pip 檢查路徑對不對。","item":1},
   {"say":"第二,在虛擬環境外面執行助理程式,結果出現找不到模組的錯誤,因為套件是裝在虛擬環境裡面的。","item":2},
   {"say":"第三,搬動專案目錄或是改名之後,虛擬環境就失效了。這是因為裡面把路徑寫死了,把點 V E N V 刪掉,重新建立就好。","item":3},
   {"say":"第四,用 sudo 去執行 pip 或是 Python。除非有很明確的理由,助理專案全程都用一般使用者就好。","item":4}
  ],
  "pip 與 requirements.txt 套件管理#1": [
   {"say":"接下來第二個單元,套件管理。在已經啟用的虛擬環境裡,我們先把 pip 升級,然後一次安裝五個套件,再用 pip list 和 pip show 看看安裝的結果。這五個套件後面都會用到。","item":0},
   {"say":"第一個是 openai,用來呼叫 L L M 的 A P I,第三章會用到。","item":1},
   {"say":"第二個是 python dotenv,負責從點 E N V 檔載入環境變數。","item":2},
   {"say":"第三個是 P S util,用來讀取 C P U、記憶體和磁碟的資訊,是第六章的主角。","item":3},
   {"say":"第四個是 pydantic,用來驗證結構化的輸出,還有工具的參數,第四、第五章會用。","item":4},
   {"say":"最後一個是 pytest,拿來寫測試。","item":5}
  ],
  "pip 與 requirements.txt 套件管理#2": [
   {"say":"裝好套件之後,要把版本固定下來。","item":0},
   {"say":"做法是用 pip freeze,把輸出存成一個叫做 requirements 的文字檔。它會列出所有套件和精確的版本,連相依的套件也包含在內。別人要還原環境的時候,用 pip install 加上減號 R,指定這個檔案就可以了。","item":1},
   {"say":"進階一點的做法,是另外維護一份只列出直接依賴的簡短清單,升級的時候比較好管理。不過在教學階段,用 pip freeze 就夠了。","item":2}
  ],
  "pip 與 requirements.txt 套件管理#3": [
   {"say":"版本鎖定之後,還是會有需要升級的時候。","item":0},
   {"say":"套件的版本會變,A P I 也可能更新。如果升級之後,程式的行為變了,先去看那個套件的更新說明。","item":1},
   {"say":"要升級單一套件,就在 pip install 後面加上兩個減號 upgrade 和套件名稱。升級完,記得跑一次測試。","item":2},
   {"say":"另外可以用 pip check,檢查套件之間的相依性有沒有衝突。","item":3}
  ],
  "pip 與 requirements.txt 套件管理#4": [
   {"say":"安裝套件的時候,也要注意供應鏈安全。","item":0},
   {"say":"第一,套件名稱要確認拼字,避免裝到名字很像的惡意套件。","item":1},
   {"say":"第二,只從官方的 PyPI 安裝。不要去執行來路不明、把網路上下載的腳本直接交給 sudo bash 執行的那種指令。","item":2},
   {"say":"第三,不要在套件清單裡,放帶有帳號密碼的私有來源網址。","item":3}
  ],
  "pip 與 requirements.txt 套件管理#5": [
   {"say":"還有一種情況很常見,就是離線或是受限制的環境。","item":0},
   {"say":"維運的主機常常不能直接連外網。這時候可以先在有網路的機器上,用 pip download 把套件下載到一個叫 wheels 的目錄,再把這個目錄搬到目標主機,用不連網的方式,指定從這個目錄安裝。","item":1}
  ],
  "pip 與 requirements.txt 套件管理#6": [
   {"say":"套件管理的常見錯誤,有這四個。","item":0},
   {"say":"第一,沒有啟用虛擬環境,就裝到系統層級去了。","item":1},
   {"say":"第二,套件清單沒有更新就部署,結果線上少了套件。所以每次新增套件之後,都要重新 freeze 一次。","item":2},
   {"say":"第三,版本沒有寫死,過了幾個月重新安裝,行為就不一樣了。","item":3},
   {"say":"第四,freeze 之後,不小心把內部的來源網址或是憑證寫進檔案。提交之前,請先看過一次內容。","item":4}
  ],
  "助理常用的 Python 語法與標準函式庫#1": [
   {"say":"第三個單元,我們來複習 Python 語法和標準函式庫。","item":0},
   {"say":"這個單元會快速帶過開發助理會用到的語法。如果你已經很熟 Python,範例大概看過去就可以了。","item":1}
  ],
  "助理常用的 Python 語法與標準函式庫#2": [
   {"say":"第一個是型別標註和 dataclass。","item":0},
   {"say":"我們的工具要回傳結構化的資料,用 dataclass 搭配型別標註,可以讓程式清楚很多。","item":1},
   {"say":"首先,從 dataclasses 模組匯入 dataclass 和 as dict 這兩樣東西。","item":2},
   {"say":"然後在類別的上面加上 dataclass 這個裝飾器,定義一個叫做 Disk Info 的類別,用來表示磁碟的資訊。","item":3},
   {"say":"最後建立一個物件,代表根目錄、總容量一百 G B、已經使用百分之八十二點五,再用 as dict 把它轉成字典印出來。","item":4}
  ],
  "助理常用的 Python 語法與標準函式庫#3": [
   {"say":"我們把類別裡面的三個欄位,拿出來仔細看。","item":0},
   {"say":"第一個欄位是 mount,掛載點,型別是字串。","item":1},
   {"say":"第二個是總容量,單位是 G B,型別是浮點數。","item":2},
   {"say":"第三個是已使用的百分比,同樣是浮點數。每個欄位後面都標上型別,別人一看就知道這份資料長什麼樣子。","item":3}
  ],
  "助理常用的 Python 語法與標準函式庫#4": [
   {"say":"第二個是用 pathlib 來處理路徑。","item":0},
   {"say":"畫面上這段程式,前半段建立一個指向系統日誌的路徑物件,檢查它存不存在,還有檔案大小。後半段示範安全的做法,先把路徑完整解析,再檢查它是不是真的在允許的目錄底下。","item":1},
   {"say":"範例裡的路徑,表面上從日誌目錄出發,卻用兩個點跳到上一層,想去讀系統的密碼檔。解析之後一比對,結果是 False,代表它不在允許的範圍裡。","item":1},
   {"say":"之後第八章的日誌工具,就會用這個技巧,只允許讀取日誌目錄底下的檔案。","item":2}
  ],
  "助理常用的 Python 語法與標準函式庫#5": [
   {"say":"第三個是 JSON,它是 L L M 和工具之間溝通的格式。","item":0},
   {"say":"程式裡用 dumps 把字典轉成 JSON 文字,其中有一個設定是用來保留中文,不要被轉成編碼。再用 loads 把文字轉回字典。","item":1},
   {"say":"要特別注意,解析 L L M 回傳的 JSON 的時候,一定要用 try except 把解析錯誤接住,因為模型有可能輸出不符合格式的內容。","item":2}
  ],
  "助理常用的 Python 語法與標準函式庫#6": [
   {"say":"第四個是例外處理。","item":0},
   {"say":"先用 try,把可能出錯的程式包起來。","item":1},
   {"say":"再用 except 指定要接住哪一種錯誤,這裡接的是 Value Error,也就是數值轉換失敗。","item":2},
   {"say":"工具函式的原則是,把例外轉成一個帶有 error 欄位的字典回傳。不要讓堆疊追蹤直接送給模型或是使用者,因為裡面可能有路徑和內部資訊。","item":3}
  ],
  "助理常用的 Python 語法與標準函式庫#7": [
   {"say":"來看 try 和 except 裡面,各放了什麼。","item":0},
   {"say":"try 裡面這一行,想把 A B C 這個字串轉成整數,這當然會失敗。","item":1},
   {"say":"失敗之後就跳到 except,印出轉換失敗,還有錯誤的原因,程式不會因此當掉。","item":2}
  ],
  "安全執行系統指令:subprocess 白名單#1": [
   {"say":"好,來到這一章最重要的單元,安全地執行系統指令。","item":0},
   {"say":"助理有一部分的工具,需要呼叫系統指令,例如查詢 Nginx 是不是在執行,或是查看磁碟空間。","item":1},
   {"say":"這是整個專案最容易出資安問題的地方。請牢牢記住,永遠不要把使用者或是模型給的文字,拼接進 shell 的指令字串裡。","item":1}
  ],
  "安全執行系統指令:subprocess 白名單#2": [
   {"say":"我們先看危險的寫法,這個請千萬不要用。","item":0},
   {"say":"畫面上的程式,是把查詢服務狀態的指令,直接跟服務名稱接在一起,交給系統執行。問題是,如果服務名稱被人填成 nginx,後面加一個分號,再接上讀取密碼檔的指令,那後面那一段也會被 shell 執行。這就叫做指令注入。","item":1},
   {"say":"另外,subprocess 的 run 如果把 shell 參數設成 True,也是一樣危險。","item":2}
  ],
  "安全執行系統指令:subprocess 白名單#3": [
   {"say":"那安全的寫法是什麼呢?三個關鍵,參數串列、白名單,再加上逾時。","item":0},
   {"say":"第一,指令用串列的方式傳進去,不經過 shell。這樣分號、管線這些特殊符號,都只會被當成普通的字元。","item":1},
   {"say":"第二,服務名稱先跟白名單比對,不在名單裡就直接拒絕。","item":2},
   {"say":"第三,設定 timeout,避免指令卡住,讓整個助理沒有回應。","item":3},
   {"say":"第四,把 check 設成 False,自己去判斷回傳碼。因為查詢服務狀態的時候,服務沒在執行就會回傳非零,這是正常的情況,不算錯誤。","item":4},
   {"say":"第五,只回傳整理過的欄位,不要把原始的錯誤輸出整段傳回去。","item":5}
  ],
  "安全執行系統指令:subprocess 白名單#4": [
   {"say":"我們對照程式碼,一段一段看。","item":0},
   {"say":"函式一開始,先檢查名稱在不在允許的服務清單裡。不在的話,馬上回傳一個錯誤,說服務不在白名單。","item":1},
   {"say":"通過檢查之後,才在 try 裡面呼叫 subprocess 的 run。指令是用串列寫的,同時設定擷取輸出,還有五秒的逾時。","item":2},
   {"say":"如果超過時間,就會被第一個 except 接住,回傳指令逾時。","item":3}
  ],
  "安全執行系統指令:subprocess 白名單#5": [
   {"say":"繼續看後半段。","item":0},
   {"say":"第二個 except 處理的是找不到檔案,也就是系統上根本沒有 system C T L 這個指令,這時候也是回傳一個錯誤訊息。","item":1},
   {"say":"都沒有問題的話,最後回傳一個字典,裡面只有服務名稱,還有去掉頭尾空白之後的狀態文字。","item":2}
  ],
  "安全執行系統指令:subprocess 白名單#6": [
   {"say":"還有一個小細節,輸出要截斷。","item":0},
   {"say":"指令的輸出有可能非常長,送進 L L M 之前要先截斷。範例的做法是設定一個上限,四千個字元,只取輸出最前面的這一段。","item":1}
  ],
  "安全執行系統指令:subprocess 白名單#7": [
   {"say":"最後談一下環境變數和 PATH。","item":0},
   {"say":"執行指令的時候,用完整路徑,或是固定的 PATH,可以降低同名程式被別人替換掉的風險。另外,第十四章把助理做成服務來執行的時候,要特別注意,那時候的 PATH 跟一般終端機裡的是不一樣的。","item":1}
  ],
  "closing": [
   {"say":"好,第二章就到這裡。我們建好了虛擬環境,學會管理套件,也知道執行系統指令的時候,一定要用參數串列、白名單和逾時。","item":0},
   {"say":"請記得把練習做一遍,再完成章末的小測驗,檢查自己學會了多少。我們下一章見。","item":1}
  ]
 }
}
