{
 "byKey": {
  "cover": [
   {"say":"大家好,我是安琪老師,歡迎來到 Linux A I 助理開發實戰。這一章,我們先不急著寫程式,先把整個助理的架構、Agent 的運作原理、安全設計原則,還有專案的目錄結構,一次看清楚。","item":0}
  ],
  "什麼是 Linux AI 助理與整體架構#1": [
   {"say":"我們先來看,這門課最後到底要做出什麼東西。","item":0},
   {"say":"整門課會一步一步,開發出一套可以在 Linux 主機上執行的 A I 助理。你可以直接用平常講話的方式問它,像是這台機器的 C P U 和記憶體狀況如何,或是 Nginx 有沒有在跑。","item":1},
   {"say":"它會自己決定要查什麼、要呼叫哪一個檢查功能,最後再用人話把結果回報給你。","item":1}
  ],
  "什麼是 Linux AI 助理與整體架構#2": [
   {"say":"那它跟我們以前寫的維運腳本,有什麼不一樣呢?傳統的腳本,只會做一件固定的事,輸出也是固定的格式。","item":0},
   {"say":"第一個差別,A I 助理的輸入是自然語言,你不需要去背指令和參數。","item":1},
   {"say":"第二,由 L L M 來負責理解你的意圖、決定步驟,還有整理結論。","item":2},
   {"say":"第三,真正去查詢主機的,是我們自己寫的、受到控制的 Python 函式,我們把它叫做工具,而不是讓 L L M 隨便下 shell 指令。","item":3},
   {"say":"這一點是全課最重要的設計原則。L L M 負責想,程式負責做,而且程式只做白名單裡面的事。","item":3}
  ],
  "什麼是 Linux AI 助理與整體架構#3": [
   {"say":"接下來看整體架構,我們由上往下,一層一層看。","item":0},
   {"say":"最上面是使用者介面,先做命令列,第十五章再做網頁版。往下是助理核心 agent,負責管理對話、迴圈和權限。","item":1},
   {"say":"再來是 L L M 層,把 A P I 呼叫包起來。提示詞層,放系統提示和輸出格式。然後是工具層,裡面有系統監控、服務、日誌、Docker、資安這些唯讀的功能。","item":1},
   {"say":"再往下是審計層,記錄誰在什麼時候要求做了什麼。最底下,才是真正的 Linux 主機。","item":1}
  ],
  "什麼是 Linux AI 助理與整體架構#4": [
   {"say":"我們用一次問答,來看資料是怎麼流動的。","item":0},
   {"say":"假設使用者問,磁碟快滿了嗎?助理會把這個問題,連同可以使用的工具清單,一起送給 L L M。L L M 回覆說,我要呼叫查詢磁碟使用量的那個工具。","item":1},
   {"say":"這時候助理程式會先檢查,這個工具在不在白名單裡,參數合不合法,確認沒問題才執行,拿到一份 JSON 結果,再把結果送回給 L L M。","item":1},
   {"say":"最後 L L M 用繁體中文整理成一句話,例如根目錄已經使用百分之八十二,建議清理日誌目錄。這句話會顯示給使用者,同時寫進審計紀錄。","item":1}
  ],
  "什麼是 Linux AI 助理與整體架構#5": [
   {"say":"這門課的章節,其實就是助理的能力地圖,我們快速看一遍。","item":0},
   {"say":"第六章做系統監控,看 C P U、記憶體和磁碟。","item":1},
   {"say":"第七章做服務檢查,包含 Apache、Nginx、MySQL 和 MongoDB。","item":2},
   {"say":"第八章是日誌分析,第九章是知識庫檢索,也就是 RAG。","item":3},
   {"say":"第十章,是 Agent 任務和授權機制。","item":4},
   {"say":"第十一章做 Docker 管理,第十二章做資安檢查。","item":5}
  ],
  "什麼是 Linux AI 助理與整體架構#6": [
   {"say":"後面還有幾章,是讓助理更完整的功能。","item":0},
   {"say":"第十三章是透過 S S H 管理多台主機,第十四章是自動化排程。","item":1},
   {"say":"第十五章做網頁介面,第十六章就是最終專題,把所有東西整合起來。","item":2}
  ],
  "什麼是 Linux AI 助理與整體架構#7": [
   {"say":"這個單元的最後,提醒三個剛開始很容易犯的錯誤。","item":0},
   {"say":"第一個,是一開始就想做萬能助理。建議你從唯讀的查詢開始,跟著章節慢慢增加能力。","item":1},
   {"say":"第二個,是以為 L L M 可以直接連到你的主機。其實 L L M 只是一個遠端的 A P I,它只會收到你送出去的文字,所有對主機的操作,都是在你自己的程式裡發生的。","item":2},
   {"say":"第三個是忽略隱私。送進 L L M A P I 的日誌,裡面可能有 I P、帳號,或是 token。第八章和第十二章,會教大家怎麼做遮罩。","item":3}
  ],
  "AI Agent 運作原理:LLM、工具與迴圈#1": [
   {"say":"好,進入第二個單元。我們先搞清楚,L L M 的本質是什麼。","item":0},
   {"say":"大型語言模型,簡單說,就是根據輸入的文字,去預測後面該接什麼文字的模型。","item":1},
   {"say":"它自己是沒有手腳的,不能讀你主機上的檔案,也不能執行 system C T L。要讓它看到主機的狀態,一定要由我們的程式先把資料查好,放進對話裡給它。","item":1}
  ],
  "AI Agent 運作原理:LLM、工具與迴圈#2": [
   {"say":"那什麼是 A I Agent 呢?最簡單的定義,就是 L L M,加上工具,再加上迴圈。","item":0},
   {"say":"第一個要素是目標,也就是使用者用自然語言說出來的需求。","item":1},
   {"say":"第二個是工具,是一組我們事先定義好的函式,每一個都有名稱、說明,還有參數的格式。","item":2},
   {"say":"第三個是迴圈。模型可以反覆進行好幾次,想一下,要求呼叫工具,看結果,再想,一直到它能回答為止。","item":3}
  ],
  "AI Agent 運作原理:LLM、工具與迴圈#3": [
   {"say":"把剛剛的觀念寫成偽碼,大概就是畫面上這個樣子。一開始,訊息裡放的是系統提示和使用者的問題,然後進入一個有回合上限的迴圈。","item":0},
   {"say":"每一回合,都把目前的訊息和工具清單交給 L L M,拿到它的回覆。","item":1},
   {"say":"如果回覆裡沒有要求呼叫工具,就代表它已經可以回答了,直接把文字傳回去,任務完成。","item":2},
   {"say":"如果有要求呼叫工具,就一個一個處理。先檢查白名單和參數,再執行工具,把結果加回訊息裡。要是超過步數上限還沒結束,就直接報錯。","item":3}
  ],
  "AI Agent 運作原理:LLM、工具與迴圈#4": [
   {"say":"實際使用的時候,常見的有三種模式。","item":0},
   {"say":"第一種是單次問答,不呼叫工具,單純問知識,這是第三章的內容。","item":1},
   {"say":"第二種是 Tool Calling,也叫函式呼叫。模型輸出的是結構化的資料,說明它想呼叫哪個函式、參數是什麼,再由程式去執行。這是第五章的主題。","item":2},
   {"say":"第三種是多步驟 Agent,可以同時診斷好幾個面向,自己規劃先後順序,我們會在第十章實作。","item":3}
  ],
  "AI Agent 運作原理:LLM、工具與迴圈#5": [
   {"say":"你可能也聽過 RAG,它在助理裡扮演什麼角色呢?","item":0},
   {"say":"RAG 的中文叫做檢索增強生成。意思是在回答之前,先從你的文件裡,例如公司的維運手冊、錯誤代碼說明,找出相關的片段,放進提示詞。","item":1},
   {"say":"它補的是模型不知道的環境知識,而 Tool Calling 補的是即時的主機資料,兩個剛好互補。細節我們留到第九章。","item":1}
  ],
  "AI Agent 運作原理:LLM、工具與迴圈#6": [
   {"say":"再來想一個問題,為什麼迴圈一定要有上限,還要留紀錄?","item":0},
   {"say":"因為模型有可能一直重複呼叫同一個工具,也有可能被日誌裡的惡意文字誘導,這叫做提示詞注入,第四章會談。","item":1},
   {"say":"所以迴圈一定要有這幾樣保護,最大步數、單次逾時、工具白名單、輸出長度截斷,還有審計紀錄。","item":1}
  ],
  "AI Agent 運作原理:LLM、工具與迴圈#7": [
   {"say":"這個單元也有三個常見錯誤,請特別注意。","item":0},
   {"say":"第一個,是以為模型輸出的指令,可以直接交給系統去執行。這是最危險的做法,我們這門課全程禁止。","item":1},
   {"say":"第二個,是沒有設定最大回合數,結果造成無限迴圈,帳單也跟著暴增。","item":2},
   {"say":"第三個,是把工具的結果原封不動塞進對話。幾萬行的日誌,一下子就超出上下文長度了。要先在程式這一端做摘要,或是截斷。","item":3}
  ],
  "安全設計原則:白名單、最小權限與審計#1": [
   {"say":"第三個單元,我們要談安全。為什麼第一章就要先講安全呢?","item":0},
   {"say":"因為一個能操作 Linux 主機的 A I,就等於一個會被自然語言驅動的管理員帳號。","item":1},
   {"say":"如果設計不好,一句話就可能造成事故。所以我們在第一章就先把規則訂下來,後面每一章都要遵守。","item":1}
  ],
  "安全設計原則:白名單、最小權限與審計#2": [
   {"say":"我們的安全設計有五大原則,先看前三個。","item":0},
   {"say":"第一是白名單。助理只能呼叫我們明確註冊過的工具。工具內部如果要執行外部指令,指令和可以用的參數,也都要在白名單裡面。","item":1},
   {"say":"注意喔,不是用黑名單去禁止某幾個危險指令,因為黑名單很容易被繞過。我們的做法是,只允許這幾個。","item":1},
   {"say":"第二是最小權限。助理用專屬的低權限使用者來執行,不用 root。需要讀日誌的時候,把這個使用者加進 A D M 群組就好,不要把 sudo 全部打開。真的需要 sudo,也只針對單一指令精準授權。","item":2},
   {"say":"第三是唯讀優先。前九章的工具全部都是唯讀的,只讀狀態、讀日誌。能查的工具,和能改的工具,要分成不同的等級。","item":3}
  ],
  "安全設計原則:白名單、最小權限與審計#3": [
   {"say":"接著是第四和第五個原則。","item":0},
   {"say":"第四,破壞性的操作一定要人工確認。像是重啟服務、停止容器、刪除檔案,都必須先顯示即將執行什麼,由人親自輸入確認之後才執行。就算模型說它已經獲得授權,也不算數。","item":1},
   {"say":"第五是審計紀錄。每一次工具呼叫,都要寫進紀錄,包含時間、使用者、工具名稱、參數、結果摘要,還有是否經過確認。紀錄檔本身,也要限制寫入的權限。","item":2}
  ],
  "安全設計原則:白名單、最小權限與審計#4": [
   {"say":"我們也建議把工具依照風險,分成四個等級。","item":0},
   {"say":"L 零是唯讀,而且沒有敏感資料,像是 C P U、記憶體、磁碟的使用率,可以直接執行。","item":1},
   {"say":"L 一也是唯讀,但是可能含有敏感資料,例如日誌和設定檔。執行之前,要視需求先遮罩帳號密碼、token 和 I P。","item":2},
   {"say":"L 二會改變狀態,不過可以復原,像是重啟服務、重新載入設定,這一級需要人工確認。","item":3},
   {"say":"L 三是很難復原的操作,像是刪除、改權限、改防火牆規則。這門課預設不提供這一類工具。","item":4}
  ],
  "安全設計原則:白名單、最小權限與審計#5": [
   {"say":"還有一個觀念很重要,哪些輸入是不能信任的?","item":0},
   {"say":"答案是,不只有使用者的輸入。日誌內容、網頁內容、檔名、容器名稱,都可能被別人控制,裡面可能夾帶像是忽略之前的指示、去執行某件事,這樣的文字。","item":1},
   {"say":"所以原則就是,這些東西只能當作資料,不能當作指令。","item":1}
  ],
  "安全設計原則:白名單、最小權限與審計#6": [
   {"say":"我們來看一個在 Ubuntu 上建立專用帳號的範例。","item":0},
   {"say":"畫面上有兩行指令。第一行建立一個叫做 A I assist 的系統帳號和同名群組,家目錄放在專案的位置。第二行把它加進 A D M 群組,目的只有一個,就是讓它能讀系統的日誌。","item":1}
  ],
  "安全設計原則:白名單、最小權限與審計#7": [
   {"say":"安全方面的常見錯誤有四個。","item":0},
   {"say":"第一,為了省事,用 root 來跑整個助理。","item":1},
   {"say":"第二,用拼接字串的方式組出 shell 指令,讓使用者的文字直接進到 shell 裡面。這個第二章會詳細說明。","item":2},
   {"say":"第三,把 A P I 金鑰寫在程式碼裡,或是提交進 git。這個第三章會講。","item":3},
   {"say":"第四,沒有審計紀錄,出事之後,完全沒辦法還原 A I 到底做過什麼。","item":4}
  ],
  "專案目錄結構與命名約定#1": [
   {"say":"最後一個單元,來看全課統一的專案結構。","item":0},
   {"say":"專案目錄的名稱固定下來,後面每一章都是在同一個專案上累積功能,所以模組的名稱請不要自己更動。","item":1},
   {"say":"畫面上這棵目錄樹,最主要的是 assistant 這個資料夾。裡面有讀設定的 config、包裝 A P I 的 L L M 模組、放提示詞的 prompts、審計用的 audit、Agent 迴圈,還有命令列入口。","item":2},
   {"say":"底下的 tools 資料夾放各種工具,像系統監控、服務、日誌、Docker 和資安。外面還有測試資料夾、放知識庫文件的 data 資料夾,以及環境變數檔。特別提醒,真正放金鑰的那個點 E N V 檔,絕對不可以提交。","item":2}
  ],
  "專案目錄結構與命名約定#2": [
   {"say":"分這麼多層,每一層的職責要劃分清楚。","item":0},
   {"say":"tools 只做查詢,然後回傳結構化的資料,不呼叫 L L M。","item":1},
   {"say":"L L M 模組只負責跟 A P I 溝通,完全不知道主機的任何細節。","item":2},
   {"say":"prompts 放所有的提示詞文字,方便做版本管理和測試。","item":3},
   {"say":"agent 把這三個串起來,並且負責白名單檢查、步數上限和審計。這樣分層之後,你可以單獨測試工具,不用花 A P I 的費用,也可以更換模型供應商,而不用動到工具。","item":4}
  ],
  "專案目錄結構與命名約定#3": [
   {"say":"好,那我們就動手把骨架建起來。","item":0},
   {"say":"畫面上的指令做三件事。先一次建立專案裡的 assistant、tools、tests 和 data 這幾個目錄,接著進入專案目錄,最後建立兩個空的初始化檔案,讓 Python 把這些資料夾當成套件。","item":1}
  ],
  "專案目錄結構與命名約定#4": [
   {"say":"接著,專案的 git 忽略清單裡,至少要有這幾項。","item":0},
   {"say":"包含虛擬環境的目錄、Python 的快取目錄、放金鑰的點 E N V 檔、所有的 log 檔,還有審計紀錄的目錄。這些都不應該進到版本庫裡面。","item":1}
  ],
  "專案目錄結構與命名約定#5": [
   {"say":"再來是全課共用的命名約定。","item":0},
   {"say":"檔名和函式名稱,一律用小寫英文,單字之間用底線連接。","item":1},
   {"say":"工具函式一律回傳字典。如果發生錯誤,就在字典裡放一個 error 欄位來回報,不要讓例外直接傳到 L L M 那邊去。","item":2},
   {"say":"工具的名稱要用動詞開頭,意思清楚。查詢類的用 get、check、list 開頭。會改變狀態的,用 restart、stop 開頭,而且要標記成需要確認。","item":3}
  ],
  "專案目錄結構與命名約定#6": [
   {"say":"最後,專案結構上也有三個常見錯誤。","item":0},
   {"say":"第一,把所有程式碼都寫進同一個檔案,到了第八章就維護不下去了。","item":1},
   {"say":"第二,把放金鑰的點 E N V 檔提交進 git。一旦推上遠端,就算之後刪掉,歷史紀錄裡還是看得到金鑰,必須馬上作廢,重新申請。","item":2},
   {"say":"第三,在工具裡面直接呼叫 L L M,這樣會很難測試,還會造成模組之間互相依賴。","item":3}
  ],
  "closing": [
   {"say":"好,第一章就到這裡。我們認識了助理的整體架構、Agent 的運作方式、五大安全原則,也把專案骨架建好了。","item":0},
   {"say":"記得動手做一下練習,再完成章末的小測驗,檢查自己學會了多少。我們下一章見。","item":1}
  ]
 }
}
