A3 — 把 CLI agent 接進安全的團隊流程¶
← Stage 5 — Track A 核心 · Track A: CLI Power User 第 3 站（核心最後一站）
這一站只做一件事：讓 CLI agent 在測試用 PR 做一個只讀檢查。它可以提出意見，但不能自己合併、部署或取得多餘權限。
📌 學習目標¶
完成後，你可以：
- 只把一個安全範圍交給 MCP server。
- 讓 CI 在 PR 自動產生一份可檢查的建議。
- 用 Observability 看懂一次執行留下的 usage、時間與結果。
- 把 A2 的 Skill 交給隊友，並讓對方安全地重跑。
🧩 先認識三個核心詞¶
| 核心詞 | 它是什麼、像什麼 | A3 怎麼用 | 不是什麼 |
|---|---|---|---|
| MCP（Model Context Protocol） | 讓 agent 連外部工具或資料的標準轉接頭 | 只把一個 demo 資料夾或唯讀工具交給 server | 不是自動安全；能碰什麼仍取決於權限 |
| CI（Continuous Integration） | push 或 PR 出現時會自動工作的檢查站 | 讓測試 PR 自動跑一次只讀 review | 不是可以跳過人類 review 的 auto-merge 按鈕 |
| Observability（觀測與紀錄） | 像收據加行車紀錄，留下發生過的事 | 記下 provider、model、usage、時間、結果與失敗原因 | 不是只看一個總 token 或猜出拿不到的成本 |
三個詞會一起出現，但不是同一件事：MCP 負責「接工具」，CI 負責「何時自動跑」，observability 負責「跑完留下什麼證據」。
先走安全階梯¶
- 只讀：先讓 agent 看資料，不讓它改資料。
- 最小權限：只開這次需要的資料夾、repo、tool 或 token scope。
- demo repo：先在可丟棄的練習環境測試。
- 人工 review：人決定要不要採用 agent 的建議。
- 最後才考慮寫入：auto-merge、push、deploy 不屬於這一站。
展開時間、先備條件、環境與費用
- 時間：先完成四個最小成果，通常可拆成數次短練習；不要為了趕時間一次接很多服務。
- 先備條件：完成 A1、A2 與 Stage 5 的 Track A 核心 5.1–5.4，並能看懂
git status、PR 與 GitHub Actions 的基本畫面。 - 環境：一個沒有真實 secrets 的 demo repo；第一輪使用 GitHub-hosted Linux runner，較容易套用 sandbox。
- 費用：GitHub Actions、CLI 訂閱與模型 API 可能分開計費。執行前先看自己使用的方案，不要把別人的價格當成自己的價格。
如果 A2 的 review-changes Skill 還不能穩定輸出 PASS 或具體問題，先回去修好再進 A3。
📚 必修閱讀¶
必讀資料與學習資源查核：2026-08-27 UTC
- 先看 MCP Connect to local servers，知道 server 只能拿到你交給它的路徑。
- 再看 GitHub Actions Security Hardening，先理解 least privilege 與不可信 PR。
- 選一條 CI 路徑：
- Claude Code：官方 GitHub Actions 文件
- Codex：官方 GitHub Action 文件
- 需要 trace、eval 或完整 production 理論時，再進 Stage 7 與 Stage 7.5。
🛠 動手練習¶
動手練習 CLI-9：只連一個 MCP server¶
成果： agent 能讀到一個新建的 demo 資料夾，但沒有取得整個 home、磁碟、真正專案或 secrets。
先複製適合你電腦的指令，建立 a3-mcp-demo/hello.txt。
PowerShell：
New-Item -ItemType Directory -Force -Path a3-mcp-demo | Out-Null
Set-Content -LiteralPath a3-mcp-demo/hello.txt -Value 'hello from A3'
macOS／Linux：
mkdir -p a3-mcp-demo
printf 'hello from A3\n' > a3-mcp-demo/hello.txt
把官方 filesystem reference server 接到你的 CLI 時，只傳入這個資料夾的絕對路徑。
成功時，agent 能讀出 hello.txt；要求它讀取範圍外的檔案時，應該失敗或要求你重新授權。
展開 CLI-9 的安裝、權限測試與 GitHub MCP 延伸
- 依你主用 CLI 的官方 MCP 文件開啟設定；不同 CLI 的設定檔與指令不一定相同。
- 使用官方 package
@modelcontextprotocol/server-filesystem，arguments 只放a3-mcp-demo的絕對路徑。不要填~、home、磁碟根目錄或整個工作區。 - 重新啟動 CLI，請它列出 demo 資料夾，再讀取
hello.txt。 - 請它讀 demo 範圍外的一個普通檔名。正確結果是拒絕或先要求新增授權；不是偷偷讀取。
- 練習後移除 server 設定，確認 CLI 已不能再使用它。
要讀 PR 或 issue 時，改看 GitHub 官方的 github/github-mcp-server。先使用 --read-only，再用 toolsets 或 tools allow-list 只開需要的能力。若使用 PAT，放在安全的 secret／環境變數，授予最少 scope，練習後撤銷；能用 OAuth 時依 host 官方流程設定。
modelcontextprotocol/servers 適合讀 reference implementation，但官方說明它們不是 production-ready。舊 github reference server 已移到歷史集合，不要再用它當現行 GitHub 入口。
費用提醒： 本機 filesystem server 通常不另外收費，但 CLI／模型仍可能計費。遠端 MCP 也可能有自己的方案。
動手練習 CLI-10：讓 PR 多一個只讀檢查員¶
成果： 測試用 PR 會留下 review 結果；人仍決定是否修改、合併或部署。
選 Anthropic 的 claude-code-action 或 OpenAI 的 codex-action。第一輪只在自己控制的 demo repo 與 branch 執行，沿用 A2 的 review-changes Skill。
成功標準不是「幾分鐘內完成」，而是 workflow 成功結束，並以 PR comment、job summary 或 artifact 留下可閱讀的結果。
展開 CLI-10 的安全設定與驗證步驟
- 從供應商的官方範例建立 workflow，不要複製來源不明的 YAML。
- API key 放入 GitHub Actions secret。不要寫進 workflow、prompt、repo 或 log。
GITHUB_TOKEN從contents: read起步。只有需要貼 PR comment 時，才對該 job 增加必要的 pull-request 權限。- Codex 的只讀工作使用目前官方 action 支援的
permission-profile: ":read-only"；不要同時設定互斥的 legacy sandbox 欄位。Claude Code 依官方 action 的 permissions／allowed tools 限制可用能力。 - prompt 只要求讀 diff、列問題、輸出
PASS或具體建議。明寫：不得 edit、commit、push、merge、deploy 或傳送額外訊息。 - 先用自己建立的 same-repo test branch。不要用
pull_request_targetcheckout 不可信 PR code；這可能讓不可信內容接觸 secrets 或寫入權限。 - 檢查 Actions log、review 結果與 repo diff。任何 secret 外洩跡象都要立即刪除 log、撤銷並輪替 secret。
GitHub 建議 production workflow 把第三方 Action pin 到完整 commit SHA，因為 tag 可能移動。官方文件中的 @v1／@v5 適合辨認產品版本；正式落地時再查證並固定當下可信的完整 SHA。
費用提醒： 設定 job timeout 與 concurrency，避免卡住或重複觸發。模型 API、供應商方案與 GitHub Actions minutes 要分開看。
動手練習 CLI-11：看一次執行的收據¶
成果： 你留下 provider／model、input usage、output usage、時間與結果；資料拿不到的欄位會清楚寫「未確認」，不會猜。
先分清你用的是訂閱方案，還是按 API usage 計費。若官方提供 token 與單價，成本才用這個算式：
input tokens × input price + output tokens × output price
展開 CLI-11 的記錄卡、停止規則與 observability
先用一個小 task 填這張卡：
| 欄位 | 要記什麼 |
|---|---|
| Task | 這次請 agent 做什麼 |
| Provider／model | 實際使用的供應商與型號；拿不到就寫未確認 |
| Usage | input／output usage；不要只寫模糊的「總 token」 |
| 時間 | workflow 或 CLI 顯示的實際耗時 |
| 結果 | PASS、問題清單或失敗原因 |
| 成本 | 只有能對到官方單價時才計算；否則寫計費方式或未確認 |
再設一個工具真的支援的停止規則，例如 job timeout、最大重試、provider spend limit，或每次進入付費步驟前人工確認。不要發明一個工具不會讀的「通用成本設定」來製造安心感。
要比較多次執行時，可選 Langfuse、Phoenix、Helicone 或 promptfoo。先確認資料會送去哪裡、是否含原始 prompt／code／PII，再決定能不能接。
Prompt caching 的 TTL、資格與價格依 provider／model 而變。Anthropic 目前文件同時提供預設 5 分鐘與可選 1 小時 TTL；把它當作要查的產品設定，不要當成所有 CLI 的固定規則。
動手練習 CLI-12：把 Skill 安全交給隊友¶
成果： 第二個乾淨 demo repo 能找到 review-changes Skill；執行後沒有非預期修改。
把 A2 的 review-changes Skill 放進可版本控制的 team repo，附上四件事：安裝位置、需要的權限、測試方法、移除方法。Claude Code 可再依官方 plugin 格式打包；其他 CLI 依各自 Skill 文件安裝。
展開 CLI-12 的分享、安裝與撤銷步驟
- 分享前讀完
SKILL.md與附帶 scripts，確認沒有下載陌生程式、讀取 secrets 或改變外部系統。 - 保留 plugin 根目錄的
skills/review-changes/SKILL.md；不要把專案自己的CLAUDE.md、AGENTS.md或 secrets 一起打包。 - 在第二個乾淨 demo repo 依工具文件安裝。Claude Code 可參考 Plugins 文件與
anthropics/claude-plugins-official。 - 做一個小文件 diff，執行 Skill，再用
git status --short確認它只 review、沒有改檔。 - 記錄版本或 commit SHA。更新前先看 diff；不再使用時，依文件移除 plugin／Skill，並確認 agent 找不到它。
Skill 的核心意思可以共用，但資料夾、權限、frontmatter 與安裝方式不一定相同。不要把某一家工具的 plugin 格式說成所有 CLI 都通用。
費用提醒： 分享檔案本身通常不收模型費，但每位隊友執行 Skill 時可能使用自己的訂閱或 API 額度。
只記得這個 production 安全迴圈¶
圈定範圍 → 只讀執行 → 留下紀錄 → 人工判斷 → 能夠復原
如果沒有範圍、證據或復原方法，就先不要提高權限。這比背很多工具名稱更重要。
📋 Playbook 4：派遣 subagent 跑獨立任務¶
成果： 先列出目前工具真的提供哪些 agent，再把獨立、可驗證的工作交出去；不要假設每台電腦都有同名 agent。
展開 Playbook 4 與其餘六個進階 playbook
Playbook 4 — subagent： subagent 是主 session 派出去的獨立小幫手。Claude Code 目前有 Explore、Plan、general-purpose 等 built-in subagent；可用清單仍會受版本、session 與設定影響。code-reviewer 是官方文件提供的自訂範例，不是每個安裝都固定存在。先執行工具的 agent list，再選 read-only agent 或建立受限 reviewer。
其餘情況只記一個動作，理論放在 Stage 7.5：
- 範圍不清： 明寫可動與不可動的路徑，先要求計畫，不先改檔。
- 多人／多 agent 平行： 分開 ownership 與 commit，最後再整合；不要同時改同一批檔案。
- Review agent 輸出： reviewer 只提供證據，不取代測試、branch protection 或人類判斷。
- 在 CI 跑 agent： 從只讀與可信 trigger 開始；模型 fallback 必須明確設定並重新驗證，不能偷偷換。
- 控制成本： 用實際 usage、timeout、重試與 provider limit；拿不到資料就說拿不到。
- 防止規則 drift： 故意做一個安全的小失敗，確認 gate 真的會擋；規則文字本身不是證據。
延伸閱讀：resources/subagent-cookbook.md與 Stage 5.5。這些頁面之後會在自己的 layer 重新查證；使用 agent 名稱前仍以你當下的官方文件與實際清單為準。
🎯 精選 Projects¶
推薦度是本學習地圖的編輯建議，不是 GitHub stars。⭐⭐⭐⭐⭐ 表示這條學習路徑的必讀／必做入口；它不代表工具永遠安全，也不代表 production 可以跳過自己的 threat model。
| 類型 | 資源 | 先看什麼 | 何時使用 | 推薦度 | 來源 |
|---|---|---|---|---|---|
| 安全連接 MCP | MCP Connect to local servers | allowed directories 與明確授權 | 第一次接本機 server | ⭐⭐⭐⭐⭐ | 官方文件 |
| MCP Security Best Practices | least privilege、scope 與 token handling | 要連帳號或遠端服務前 | ⭐⭐⭐⭐⭐ | 官方文件 | |
github/github-mcp-server | --read-only、toolsets 與 tools allow-list | 要讀 GitHub PR／issue | ⭐⭐⭐⭐ | GitHub repo | |
modelcontextprotocol/servers | reference implementation 與非 production-ready 警告 | 學協定或讀範例程式 | ⭐⭐⭐⭐⭐ | GitHub repo | |
| CI 與 PR review | GitHub Actions Secure Use | 最小權限、不可信輸入、pin SHA | 寫任何有 secrets 的 workflow 前 | ⭐⭐⭐⭐⭐ | 官方文件 |
| Claude Code GitHub Actions | 官方 setup、permissions 與 troubleshooting | 使用 Claude Code 跑 CI | ⭐⭐⭐⭐⭐ | 官方文件 | |
anthropics/claude-code-action | 官方範例與 action inputs | 從可執行範本開始 | ⭐⭐⭐⭐⭐ | GitHub repo | |
| Codex GitHub Action | permission profile、trigger 與輸出 | 使用 Codex 跑 CI | ⭐⭐⭐⭐⭐ | OpenAI 官方文件 | |
openai/codex-action | :read-only 與 safety strategy | 核對最新 inputs 與範例 | ⭐⭐⭐⭐⭐ | GitHub repo | |
| 觀察與評估 | langfuse/langfuse | traces、usage 與 eval | 想把多次執行放在一起看 | ⭐⭐⭐⭐⭐ | GitHub repo |
Arize-ai/phoenix | tracing 與 evaluation | 想用開放原始碼觀察 AI 系統 | ⭐⭐⭐⭐ | GitHub repo | |
Helicone/helicone | proxy／gateway 的資料流與隱私邊界 | 想從 gateway 收集 request 紀錄 | ⭐⭐⭐⭐ | GitHub repo | |
promptfoo/promptfoo | eval cases 與 CI regression | 要比較改動前後是否退步 | ⭐⭐⭐⭐⭐ | GitHub repo | |
| 分享 Skill／plugin | Claude Code Plugins | plugin 結構、安裝與 marketplace | 要替 Claude Code 打包 | ⭐⭐⭐⭐ | 官方文件 |
anthropics/claude-plugins-official | 官方管理的 plugin 目錄 | 找可讀的正式範例 | ⭐⭐⭐⭐⭐ | GitHub repo | |
obra/superpowers-marketplace | 最小 marketplace 外殼 | 理解 curator-only 結構 | ⭐⭐⭐ | GitHub repo | |
| 目錄與完整範例 | wong2/awesome-mcp-servers | 先分類，再逐一查來源與權限 | 官方資源沒有需要的 server 時 | ⭐⭐⭐⭐ | GitHub repo |
obra/superpowers | Skill、規則與 workflow 如何組在一起 | 完成最小流程後看完整例子 | ⭐⭐⭐⭐ | GitHub repo |
目錄只幫你「找到候選項」，不替候選項保證安全。安裝任何 MCP、Action、Skill 或 plugin 前，都要再看 source、權限、最近維護狀態與移除方法。
✅ Track A 完成檢查¶
- MCP 只拿到 demo 資料夾或最小 read-only toolset。
- PR workflow 只提出意見，沒有 auto-merge、push 或 deploy。
- secrets 不在 repo、prompt 或 log；workflow 使用最小權限。
- 我能指出一次執行的結果與 usage；拿不到的資料沒有亂猜。
- 隊友能在乾淨 demo repo 執行 Skill，之後
git status沒有非預期修改。
五項都做到，就完成 Track A 核心。建議下一站讀 Stage 8 — Agent 操作介面，學會怎麼替 Browser、Computer 與 Sandbox 設安全邊界；Stage 8 不擋 Track A Capstone 入場。想自己寫 agent，再回到 Stage 3。