{
 "byKey": {
  "cover": [
   {"say":"大家好,歡迎回到 Linux A I 助理開發實戰。這一章要讓 A I 安全地呼叫 Linux 工具,也就是 Tool Calling。我們會看它的運作原理、怎麼安全地執行系統指令、建立工具註冊機制,最後把對話迴圈、人工確認和審計串起來。","item":0}
  ],
  "Tool Calling 的運作原理#1": [
   {"say":"先想一下,為什麼需要 Tool Calling?因為 L L M 只會產生文字,它看不到你的主機,也不能執行任何指令。你問它這台機器開機多久了,沒有工具的模型只能憑空猜,猜出來的數字就是幻覺。","item":0},
   {"say":"Tool Calling 的做法是,你先告訴模型有哪些工具、各需要什麼參數。模型需要的時候,就回覆說請幫我呼叫某個工具,由你的程式真正去執行,再把結果交還給它。重點是,模型從頭到尾不執行任何東西,執行的永遠是你的 Python 程式。","item":0},
   {"say":"完整的流程有五步。第一步,把訊息和工具清單一起送出去。","item":1},
   {"say":"第二步,模型回傳它想呼叫的工具,或者直接回答。","item":2},
   {"say":"第三步,由程式驗證,然後執行工具。","item":3},
   {"say":"第四步,把結果用 tool 這個角色的訊息送回去,並且帶上對應的呼叫編號。送回去之前,要先把模型那則要求呼叫工具的訊息,原樣加進訊息串列裡。","item":4},
   {"say":"第五步,一直重複,直到模型不再要求工具,我們就得到最終的回答。另外,一次回應裡可能同時要求好幾個工具,每一個都要各自回覆一則 tool 訊息。","item":5}
  ],
  "Tool Calling 的運作原理#2": [
   {"say":"這裡有幾個很常見的錯誤,我們一個一個看。","item":0},
   {"say":"第一,模型給的參數其實是一段 JSON 字串,不是字典。很多人忘了先用 JSON 的 loads 解析,就直接拿來用。","item":1},
   {"say":"第二,忘記把模型要求呼叫工具的那則訊息放回訊息串列,結果 A P I 回報說,tool 訊息找不到對應的呼叫。","item":2},
   {"say":"第三,tool 訊息漏了呼叫編號,或是編號對不上。","item":3},
   {"say":"第四,工具的描述寫得太含糊,例如只寫查詢系統,模型就會選錯工具。描述要寫清楚,什麼時候該用這個工具。","item":4},
   {"say":"第五,沒有限制迴圈的次數,模型反覆呼叫工具,造成無限迴圈,費用也跟著暴增。","item":5}
  ],
  "Tool Calling 的運作原理#3": [
   {"say":"還有一個錯誤,跟模型的選擇有關。","item":0},
   {"say":"就是用了不支援工具呼叫的模型。這個能力每個模型不一樣,請查你所用模型的文件。模型名稱一樣放在環境變數裡,不要寫死在程式碼裡。","item":1}
  ],
  "Tool Calling 的運作原理#4": [
   {"say":"我們對照實際的訊息格式來看。這門課用的是 OpenAI 風格的格式,很多供應商和開源的推論伺服器都相容,不過實際的欄位細節,還是要以你所用服務的官方文件為準。","item":0},
   {"say":"第一步,請求的時候附上工具清單。每個工具要寫名稱、描述,還有用 JSON Schema 描述的參數。範例是一個查詢開機時間的工具,它不需要任何參數。","item":1},
   {"say":"清單到這裡結束。描述裡面特別寫了,使用者問開機時間的時候呼叫,這就是在告訴模型什麼時候該用。","item":2},
   {"say":"第二步,模型如果決定要用工具,回傳的訊息裡不會有最終答案,內容是空的,但是會帶著工具呼叫的清單,裡面有編號、函式名稱和參數。","item":3}
  ],
  "Tool Calling 的運作原理#5": [
   {"say":"接著是第三步和第四步。","item":0},
   {"say":"第三步,你執行完工具,把結果包成一則角色是 tool 的訊息送回去,帶上剛剛那個呼叫編號,內容就是工具的結果。第四步,再呼叫一次模型,它讀到工具結果之後,才產生自然語言的答案。","item":1}
  ],
  "安全執行系統指令#1": [
   {"say":"第二個單元,安全執行系統指令。先想想,是誰在對你的工具下指令?以前是你自己,現在是模型。而模型的輸入可能來自使用者、日誌、網頁,任何一個都可能被惡意操控。所以模型產生的參數,要當成不可信的輸入。我們有八條底線。","item":0},
   {"say":"第一條,白名單。只有明確登錄的工具、明確列出的執行檔,才可以被呼叫。不是用黑名單去擋危險指令。","item":1},
   {"say":"第二條,絕對不使用 shell 等於 True 的寫法,也不要讓模型提供一整串的指令字串。","item":2},
   {"say":"第三條,參數用陣列的方式傳遞,不經過 shell 解析。這樣分號、管線、反引號,都只是普通的字元。","item":3},
   {"say":"第四條,輸入驗證。用 JSON Schema 裡的列舉值、格式樣式、最小值、最大值來約束參數,驗證失敗就拒絕。","item":4}
  ],
  "安全執行系統指令#2": [
   {"say":"繼續看第五到第七條。","item":0},
   {"say":"第五條,唯讀優先。先做查詢類的工具。會改變系統狀態的工具,要另外標記,而且需要人工確認。","item":1},
   {"say":"第六條,逾時和輸出限制。每個指令都要有 timeout,輸出也要截斷,避免卡死,或是把巨量的文字塞進 L L M。","item":2},
   {"say":"第七條,審計紀錄。誰、什麼時候、呼叫哪個工具、用什麼參數、結果的狀態,通通寫進日誌。","item":3}
  ],
  "安全執行系統指令#3": [
   {"say":"最後一條底線,還有一個容易被忽略的問題,叫做選項注入。","item":0},
   {"say":"第八條,最小權限。助理用專用的低權限帳號執行,需要提升權限的時候,用 sudoers 精準地授權單一指令。","item":1},
   {"say":"再來說選項注入。就算沒有經過 shell,如果參數值是減號開頭,還是可能被目標程式當成選項。第一個對策,是用格式樣式來驗證,例如服務名稱只允許英文、數字和少數幾個符號,而且不可以用減號開頭。","item":2},
   {"say":"第二個對策,能用列舉值,就用列舉值。","item":3},
   {"say":"第三個對策,指令有支援的話,用兩個減號把選項和位置參數隔開,或是用把值直接黏在選項後面的寫法。","item":4}
  ],
  "安全執行系統指令#4": [
   {"say":"這個單元的常見錯誤,先看四個。","item":0},
   {"say":"第一,以為把參數加上引號跳脫,再配合 shell 執行就安全了。只要漏掉一個地方就破功,直接不用 shell 最簡單。","item":1},
   {"say":"第二,把好幾種執行指令的方式,跟 shell 模式混在一起用。","item":2},
   {"say":"第三,沒有設定環境變數,結果子程序繼承了使用者的環境變數,裡面還包含 A P I 金鑰。我們的範例,用的是一組乾淨的安全環境變數。","item":3},
   {"say":"第四,把錯誤輸出全部回傳給模型,可能會洩漏路徑或是設定細節。範例只保留前面兩千個字元。","item":4}
  ],
  "安全執行系統指令#5": [
   {"say":"最後還有一個很實用的原則。","item":0},
   {"say":"如果資訊可以用 Python 的函式庫取得,像是 P S util,或是直接讀系統的 proc 目錄,就不要啟動子程序,這樣攻擊面更小。","item":1}
  ],
  "安全執行系統指令#6": [
   {"say":"我們來看安全執行模組的程式碼,它放在 assistant 資料夾裡,檔名是 safe exec。","item":0},
   {"say":"一開始匯入 subprocess 模組。","item":1},
   {"say":"再匯入 dataclass,等一下用來定義指令結果的資料結構。","item":2},
   {"say":"然後定義一個自己的例外類別,叫做 Exec Error。之後所有執行上的問題,都用這個例外來表示。","item":3}
  ],
  "安全執行系統指令#7": [
   {"say":"接著是整個模組的核心,白名單。","item":0},
   {"say":"註解說得很清楚,白名單是把邏輯名稱,對應到執行檔的絕對路徑。路徑要先在你自己的系統上,用 command 減號 V 確認過。","item":1},
   {"say":"範例登錄了四個指令,uptime、D F、system C T L,還有 journal C T L,每一個都寫絕對路徑。","item":2},
   {"say":"名單到這裡結束。後面的執行函式,會先查這份名單,不在裡面的直接報錯。在名單裡的,才用陣列參數、乾淨的環境變數、十秒逾時去執行,輸出太長還會截斷。","item":3}
  ],
  "建立工具註冊機制#1": [
   {"say":"第三個單元,建立工具註冊機制。這門課所有的工具,都透過同一個註冊中心登錄,它同時扮演三個角色。","item":0},
   {"say":"第一個角色是工具清單,負責產生要送給模型的工具描述。","item":1},
   {"say":"第二個角色是白名單,不在註冊表裡的工具名稱,一律拒絕。","item":2},
   {"say":"第三個角色是執行閘門,把 JSON 解析、參數驗證、人工確認、輸出截斷、審計紀錄,集中在同一個地方做。這樣新增工具的時候,只要寫一個函式,加一個裝飾器就好,安全邏輯不會漏掉。","item":3},
   {"say":"常見的錯誤,第一個是在好幾個地方各自做白名單,這樣很容易出現漏洞。請統一走註冊中心。","item":4},
   {"say":"第二個,是 Schema 裡沒有寫不允許額外屬性,程式又沒有檢查多餘的參數,模型就可能塞進你沒預期的參數。","item":5}
  ],
  "建立工具註冊機制#2": [
   {"say":"還有兩個常見錯誤。","item":0},
   {"say":"一個是工具函式回傳的內容裡,有日期時間這類沒辦法直接轉成 JSON 的物件。下一個單元的執行函式,會把這種物件自動轉成字串來處理。","item":1},
   {"say":"另一個是工具名稱重複註冊,卻無聲無息地被覆蓋掉。我們的範例選擇直接丟出錯誤,讓問題在啟動的時候就浮現。","item":2}
  ],
  "建立工具註冊機制#3": [
   {"say":"來看註冊中心的程式碼,我們分幾張慢慢看。","item":0},
   {"say":"第一行,一次匯入 JSON、O S、正規表示式、time 和 logging 這幾個標準模組。","item":1},
   {"say":"第二行匯入 dataclass。","item":2},
   {"say":"第三行匯入型別標註會用到的 Any 和 Callable。","item":3},
   {"say":"然後建立這個模組專用的 logger。","item":4}
  ],
  "建立工具註冊機制#4": [
   {"say":"接著是幾個設定。","item":0},
   {"say":"第一個是工具結果的長度上限,八千個字元。","item":1},
   {"say":"第二個是審計紀錄檔的路徑,先從環境變數讀,沒有設定的話,就用 logs 目錄底下的預設檔案。","item":2},
   {"say":"第三個是 Tool Error 這個例外類別。它代表的是可以安全回報給模型的錯誤訊息。","item":3}
  ],
  "建立工具註冊機制#5": [
   {"say":"再來是工具本身的資料結構。","item":0},
   {"say":"這個 dataclass 設定成凍結的,也就是建立之後就不能再修改。","item":1},
   {"say":"Tool 類別裡有名稱、描述、參數格式、實際要執行的函式,還有兩個旗標,是否唯讀,以及是否需要確認。預設是唯讀、不需要確認。","item":2},
   {"say":"下面這個字典就是註冊表,用工具名稱當作鍵。","item":3},
   {"say":"最後這個常數,是一份空的參數格式,給不需要任何參數的工具使用。","item":4}
  ],
  "建立工具註冊機制#6": [
   {"say":"有了資料結構,接著是兩個重要的函式。","item":0},
   {"say":"第一個是 register,它是一個裝飾器。用它來標記函式,函式就會被登錄到註冊表裡。有兩個細節,只要工具不是唯讀,就一律需要確認。還有,名稱重複註冊會直接報錯。","item":1},
   {"say":"第二個函式是 schemas,它把註冊表裡所有的工具,轉成要送給模型的工具清單格式。","item":2}
  ],
  "建立工具註冊機制#7": [
   {"say":"最後是參數驗證。模型給的參數,不保證符合你訂的格式,一定要自己檢查。","item":0},
   {"say":"第一行是型別的對照表,把 Schema 裡的字串、整數、數字、布林,對應到 Python 的型別。","item":1},
   {"say":"驗證函式會依序檢查,參數是不是物件、有沒有多餘的參數、必要的參數有沒有缺、型別對不對,還有列舉值、最小值、最大值和格式樣式。","item":2},
   {"say":"有兩個要特別注意的地方。Python 的布林其實是整數的子類別,所以要先排除布林值被當成整數的情況。還有,比對格式要用完整比對,避免只比對到前面一段就通過。","item":2}
  ],
  "對話迴圈、確認與審計#1": [
   {"say":"最後一個單元,把對話迴圈、確認和審計串起來。所有工具都要經過同一個執行閘門。發生錯誤的時候,轉成 ERROR 開頭的文字回給模型,讓它有機會修正,但是不回傳程式的錯誤追蹤。先看四個常見錯誤。","item":0},
   {"say":"第一,迴圈沒有設最大回合數的上限。","item":1},
   {"say":"第二,把工具結果直接印出來,卻沒有放進訊息串列,模型根本看不到。","item":2},
   {"say":"第三,確認函式預設成同意。預設一定要是拒絕,沒有確認,就等於不同意。","item":3},
   {"say":"第四,測試只靠真實的 L L M,結果很難重現。建議用一個假的 chat 函式來驗證流程。","item":4}
  ],
  "對話迴圈、確認與審計#2": [
   {"say":"我們來看程式碼。","item":0},
   {"say":"第一個函式負責寫審計紀錄。它把每一筆紀錄轉成一行 JSON,附加到審計檔的最後面。就算寫入失敗,也只是記錄錯誤,不會讓整個程式停下來。","item":1},
   {"say":"第二個是執行閘門 call tool。它先查註冊表,再解析參數、驗證參數。需要確認的工具,沒有得到同意就取消。然後才執行,最後截斷過長的輸出,寫一筆審計紀錄,記下工具、參數、狀態和花費的時間。","item":2},
   {"say":"提醒一下,審計檔要設定好權限,而且不要記錄機密的參數。確認畫面要顯示的,是實際要執行的工具和參數,不是模型自己寫的說明,因為說明文字可能被誘導。","item":2},
   {"say":"再往下,就是對話迴圈的檔案了,檔名叫做 loop,開頭先匯入 JSON 模組。","item":3}
  ],
  "對話迴圈、確認與審計#3": [
   {"say":"對話迴圈的開頭,還有三行匯入。","item":0},
   {"say":"第一行,從 assistant 匯入第三章寫的 L L M 模組。","item":1},
   {"say":"第二行,從註冊中心匯入剛剛看到的 schemas 和 call tool。","item":2},
   {"say":"第三行匯入整個 tools 套件。它看起來沒有被用到,但是一匯入,就會觸發各個工具模組去註冊。","item":3}
  ],
  "對話迴圈、確認與審計#4": [
   {"say":"接著處理系統提示,還有回合上限。","item":0},
   {"say":"先嘗試從第四章的 prompts 檔案,匯入系統提示。","item":1},
   {"say":"如果匯入失敗,就用一段預設的提示詞,告訴模型你是 Linux 主機維運助理,主機資訊只能來自工具結果,不要編造數據。","item":2},
   {"say":"然後把最大回合數設成五。","item":3}
  ],
  "對話迴圈、確認與審計#5": [
   {"say":"最後是整個迴圈的主角。","item":0},
   {"say":"這個 ask 函式,先把系統提示和使用者的問題放進訊息串列,然後最多跑五個回合。每一回合呼叫模型,如果沒有要求工具,就直接回傳答案。有的話,先把模型的訊息放回去,再逐一執行工具,把結果加進訊息裡。超過上限,就請使用者縮小問題的範圍。","item":1},
   {"say":"這裡假設第三章的 chat 函式回傳的是字典。如果你的版本回傳的是 S D K 的物件,要先轉成字典,做法請參考 S D K 的文件。","item":1},
   {"say":"最下面這一段,讓這個檔案可以直接從命令列執行。沒有給問題的話,預設會問,這台主機開機多久了?","item":2}
  ],
  "closing": [
   {"say":"好,第五章就到這裡。我們學會了 Tool Calling 的流程、安全執行指令的八條底線,也完成了註冊中心、執行閘門和對話迴圈。","item":0},
   {"say":"這一章的程式比較多,請一定要動手做練習,再完成章末的小測驗,檢查自己學會了多少。我們下一章見。","item":1}
  ]
 }
}
