教學

OpenTelemetry教學手冊 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 前一版本 1.0（2026-01-27） 版本基準 OpenTelemetry Collector / Contrib v0.162.0（2026-09-29）、Helm Chart opentelemetry-collector 0.174.0、Operator v0.160.0、Java Agent 2.31.1、Java SDK 1.66.0、JS SDK 2.11.0、Semantic Conventions 1.44.0、Specification 1.61.0、OTLP 1.11.1；完整矩陣見 附錄 D.1 適用對象 後端工程師、DevOps / SRE、平台工程團隊、系統架構師、資安與稽核人員 文件定位 企業標準技術白皮書：概念 → 架構 → 安裝 → 設定 → 應用串接 → 維運 → 升級 → 治理 驗證方式 文中 Collector 設定以 otelcol-contrib 0.162.0 validate 驗證；PromQL 與告警規則以 promtool 3.15.0 check rules 驗證；查證紀錄見 附錄 E 作者 Eric Cheng 📌 v2.0 改版重點 ...

Apache Kafka 教學手冊 項目 內容 文件版本 2.0 最後更新 2026 年 9 月 29 日 適用版本 Apache Kafka 4.3.x（KRaft 模式；ZooKeeper 模式已於 4.0 移除） 適用對象 後端工程師、系統架構師、SRE、DevOps、資安與稽核人員 文件定位 企業標準技術白皮書／內部標準教材 使用情境 大型企業、金融業（銀行、證券、保險）內部系統 文件維護 內部技術團隊 Created by Eric Cheng ⚠️ v2.0 重大改版說明：本版以 Apache Kafka 4.3（最新修補版 4.3.1）為基準全面改寫。v1.0 以 Kafka 3.x／ZooKeeper 並存時代為基準，其中 inter.broker.protocol.version 升級流程、zookeeper.connect ACL 指令、config/kraft/ 設定路徑等內容在 4.x 已不適用。完整更正清單請見附錄 E：版本更新紀錄，查證來源請見附錄 F：查證紀錄。 目錄 執行摘要 1. Apache Kafka 簡介 1.1 Kafka 是什麼？解決什麼問題？ 1.2 與傳統 Message Queue 的差異 1.3 適合與不適合的使用情境 1.4 核心概念與五大 API 1.4.1 事件（Event）結構 1.4.2 核心術語 1.4.3 五大 API 1.5 版本演進與 4.x 重點 1.5.1 近期版本時間軸 1.5.2 4.x 對企業的關鍵影響 1.6 💡 本章實務建議 2. Kafka 系統架構總覽 2.1 Kafka 核心元件說明 2.1.1 Broker 2.1.2 Topic 與 Partition 2.1.3 Producer 2.1.4 Consumer 與 Consumer Group 2.1.5 Controller 與 KRaft Metadata Quorum 2.1.6 Share Group（Queues for Kafka） 2.2 高可用（HA）與水平擴充設計原則 2.2.1 副本機制（Replication） 2.2.2 高可用設計原則 2.2.3 機架感知（Rack Awareness） 2.2.4 水平擴充原則 2.3 儲存層架構 2.3.1 Log Segment 結構 2.3.2 高效能設計 2.4 Tiered Storage（分層儲存） 2.5 💡 本章實務建議 3. Kafka 安裝與部署 3.1 環境需求 3.1.1 硬體需求 3.1.2 軟體需求 3.1.3 網路需求 3.2 單機環境安裝（KRaft 模式） 3.3 多節點叢集安裝（正式環境） 3.3.1 叢集規劃 3.3.2 Controller 節點設定 3.3.3 Broker 節點設定 3.3.4 叢集初始化與啟動 3.3.5 Controller 動態擴縮 3.4 ZooKeeper 移除與遷移路徑 3.5 常見安裝錯誤與排除方式 3.6 Docker 容器部署 3.6.1 快速啟動 3.6.2 以環境變數設定 3.6.3 Docker Compose 範例（單節點開發環境） 3.7 Kubernetes 部署 3.8 系統服務與作業系統調校 3.8.1 Systemd Service 3.8.2 JVM 調校 3.8.3 作業系統調校 3.9 💡 本章實務建議 4. Kafka 基本設定說明 4.1 Broker 重要設定參數 4.1.1 核心設定 4.1.2 效能相關設定 4.1.3 日誌與可靠性設定 4.1.4 Kafka 4.0 預設值變更 4.2 Topic 設計原則 4.2.1 Partition 數量設計 4.2.2 Replication Factor 設計 4.2.3 Topic 層級設定 4.3 Producer 重要設定 4.4 Consumer 重要設定 4.5 資料保留策略（Retention Policy） 4.6 Share Group 設定 4.7 動態設定管理 4.8 💡 本章實務建議 5. Kafka 系統使用教學 5.1 Topic 管理 5.1.1 建立 Topic 5.1.2 查詢 Topic 5.1.3 修改 Topic 5.1.4 刪除 Topic 5.2 Producer 發送訊息 5.2.1 使用 Console Producer 5.2.2 Java Producer 範例 5.3 Consumer 消費訊息 5.3.1 使用 Console Consumer 5.3.2 Java Consumer 範例 5.4 Offset 管理 5.4.1 查看 Consumer Group Offset 5.4.2 重置 Offset 5.4.3 群組管理工具（KIP-1043） 5.5 訊息順序性與重複消費 5.5.1 訊息順序保證 5.5.2 避免重複消費 5.6 Share Group 操作 5.6.1 Console Share Consumer 5.6.2 管理 Share Group 5.6.3 Java Share Consumer 範例 5.7 交易與 Exactly-Once 語意 5.7.1 傳遞語意比較 5.7.2 交易 Producer（Consume-Transform-Produce） 5.8 💡 本章實務建議 6. Kafka 與應用系統串接方式 6.1 與 Spring Boot 整合 6.1.1 Maven 依賴 6.1.2 設定檔（application.yml） 6.1.3 Producer 實作 6.1.4 Consumer 實作 6.1.5 Kafka 設定類別與錯誤處理 6.1.6 非阻塞重試（@RetryableTopic） 6.1.7 Share Consumer 整合 6.2 系統解耦架構設計 6.3 同步系統 vs 事件驅動架構 6.4 常見整合架構模式 6.4.1 Event Sourcing 6.4.2 CDC（Change Data Capture） 6.4.3 Saga 模式 6.4.4 Transactional Outbox 模式 6.5 Schema Registry 與 Schema 演進 6.6 Kafka Connect 與 CDC 6.7 Kafka Streams 串流處理 6.8 💡 本章實務建議 7. Kafka 系統維運與監控 7.1 常見監控指標 7.1.1 Broker 層級指標 7.1.2 Controller 與 KRaft 指標 7.1.3 Topic／Partition 層級指標 7.1.4 Client 層級指標 7.2 Consumer Lag 監控與處理 7.2.1 查看 Consumer Lag 7.2.2 Lag 過高的原因與解決方案 7.3 系統監控設定 7.3.1 JMX 監控設定 7.3.2 Prometheus 整合 7.3.3 Grafana Dashboard 7.4 常見營運問題與排查 7.4.1 問題排查流程 7.4.2 常見問題與解決方案 7.4.3 日誌檢查 7.5 容量規劃與效能調校 7.5.1 儲存容量估算 7.5.2 網路頻寬估算 7.5.3 效能調校對照表 7.5.4 壓力測試 7.6 叢集維護作業 7.6.1 Partition 重新分配 7.6.2 Preferred Leader 選舉 7.6.3 Cordon（隔離）Broker 與磁碟（KIP-1066） 7.6.4 Broker 下線流程 7.7 災難復原與跨機房部署 7.7.1 部署模式比較 7.7.2 MirrorMaker 2 7.7.3 備份策略 7.8 💡 本章實務建議 8. Kafka 系統升級與版本控管 8.1 升級策略（Rolling Upgrade） 8.1.1 版本控管概念 8.1.2 升級前提（升級至 4.3） 8.1.3 升級步驟 8.2 升級前檢查清單 8.3 升級風險與回復機制 8.3.1 常見風險 8.3.2 回滾步驟 8.4 Client 相容性 8.4.1 官方相容性摘要（Kafka 4.x） 8.4.2 Java 版本需求 8.4.3 升級順序建議 8.5 3.x 升級至 4.x 破壞性變更 8.6 版本支援與發布週期 8.7 💡 本章實務建議 9. 安全性與權限控管 9.1 SSL/TLS 加密 9.1.1 建立 SSL 憑證 9.1.2 Broker SSL 設定 9.2 SASL 認證 9.2.1 認證機制比較 9.2.2 SASL/SCRAM 設定 9.2.3 Client 端設定 9.2.4 SASL/OAUTHBEARER（OIDC） 9.2.5 Controller Listener 安全 9.3 ACL 權限控管 9.3.1 啟用 Authorizer 9.3.2 設定 ACL 9.3.3 常見 ACL 權限 9.4 企業安全設計建議 9.5 機密管理與身分對應 9.5.1 Config Provider 9.5.2 mTLS 身分對應 9.6 稽核、配額與合規 9.6.1 Authorizer 稽核日誌 9.6.2 Client Quota 9.6.3 金融業合規考量 9.7 💡 本章實務建議 10. 最佳實務與常見地雷 10.1 Topic 命名建議 10.1.1 命名規範 10.2 Partition 設計地雷 10.2.1 常見錯誤 10.2.2 Partition 數量計算 10.3 Consumer Group 錯誤案例 10.3.1 案例 1：Consumer 數量超過 Partition 10.3.2 案例 2：誤用 Consumer Group 10.3.3 案例 3：Rebalance 風暴 10.3.4 案例 4：Kubernetes 滾動部署造成反覆 Rebalance 10.4 真實專案常見誤用情境 10.4.1 將 Kafka 當作資料庫使用 10.4.2 忽略冪等性設計 10.4.3 同步呼叫與非同步混用（雙寫問題） 10.4.4 大訊息傳輸 10.4.5 其他常見地雷 10.5 最佳實務總結 10.6 Consumer Group 與 Share Group 選型 10.7 事件設計規範 10.7.1 事件信封（Envelope）標準 10.7.2 事件設計原則 11. 檢查清單（Checklist） 11.1 新專案導入 Checklist 11.1.1 規劃階段 11.1.2 部署階段 11.1.3 開發階段 11.1.4 上線前 11.2 日常維運 Checklist 11.2.1 每日檢查 11.2.2 每週檢查 11.2.3 每月檢查 11.3 故障排除 Checklist 11.3.1 Controller 問題 11.3.2 Broker 問題 11.3.3 Producer 問題 11.3.4 Consumer 問題 11.4 升級 Checklist 11.4.1 升級前 11.4.2 升級中 11.4.3 升級後 附錄 附錄 A：常用指令速查 A.1 叢集與 Metadata A.2 Topic 管理 A.3 設定管理 A.4 Group 管理 A.5 Console Producer／Consumer A.6 維運作業 附錄 B：設定參數速查 B.1 Broker／Controller 重要參數 B.2 Producer 重要參數 B.3 Consumer 重要參數 B.4 Group 層級參數（Broker 端控制） 附錄 C：參考資源 C.1 官方文件（Apache Kafka 4.3） C.2 版本發布與 KIP C.3 社群資源 C.4 生態系與延伸閱讀 附錄 D：名詞對照表 附錄 E：版本更新紀錄 E.1 版本歷程 E.2 v2.0 主要更正 E.3 v2.0 新增章節 附錄 F：查證紀錄 F.1 待後續確認事項 執行摘要 Apache Kafka 是目前企業界事實上的**事件串流平台（Event Streaming Platform）**標準。它同時具備「發布／訂閱」、「持久化儲存」與「串流處理」三種能力，使企業能以單一平台串接交易系統、資料平台、監控系統與 AI／分析應用。 ...

Redis教學手冊 項目 內容 文件版本 2.0 最後更新 2026 年 9 月 29 日 初版日期 2026 年 1 月 27 日（v1.0） 適用版本 Redis Open Source 8.10.x（最新修補版 8.10.2，2026-09-17）；向下相容說明涵蓋 7.2 / 7.4 / 8.0～8.8 適用對象 資深／中階後端工程師、系統架構師、SRE、DevOps、DBA、資安與稽核人員、新進同仁 文件定位 企業標準技術白皮書／內部標準教材 審閱週期 每季檢視一次；Redis 發布新 minor 版本或重大 CVE 時即時更新 Created by Eric Cheng ⚠️ v2.0 重大改版說明：v1.0 以 Redis 7.2 為基準撰寫。自 2025 年 5 月起 Redis 進入 8.x 世代：Redis Stack 模組（JSON、Query Engine、Time Series、機率型資料結構）併入 Redis Open Source、授權新增 AGPLv3 選項、新增 Vector Set 與 Array 資料型態，並連續修補多個可導致遠端程式碼執行（RCE）的 CVE。本版以 Redis 8.10.2 為基準全面檢視每一章，修正 v1.0 約 40 處過時或錯誤內容，並新增第 14、15 章與附錄 B～E。完整更正清單請見附錄 C：版本更新紀錄，逐項查證來源請見附錄 D：查證紀錄。 ...

Logstash / Elasticsearch / Kibana（ELK Stack）教學手冊 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 版本基準 Elastic Stack 9.5.4（2026-09-15 發佈）：Elasticsearch／Logstash／Kibana／Filebeat 同版；相容說明涵蓋 8.19.x（支援至 2027-07-15） 文件定位 企業標準技術白皮書／內部標準教材 適用對象 資深軟體工程師、系統架構師、SRE／DevOps 工程師、資安與稽核人員 前置知識 Linux 基礎、Java／Spring Boot 應用程式、基本網路與 TLS 概念 使用情境 企業級 Logs Visualization 平台（與 Prometheus／Grafana 並存的 Observability 架構） 前一版本 1.0（2026-01-29，以 Elastic Stack 8.12 為基準） Created by Eric Cheng 📌 v2.0 改版重點：全面對齊 Elastic Stack 9.5；修正 v1.0 中已移除、已失效或錯誤的設定（_flush/synced、yum downgrade、Filebeat type: log、Logstash ssl => false、elasticsearch.yml 內的 index 層級設定、Kibana i18n.locale: "zh-TW"、ILM freeze 等）；改以 Data Stream、ECS、API Key 與 TLS 為預設做法；新增授權層級、容量規劃、Data Tiers、ES|QL、Alerting、Streams、Snapshot／SLM、OpenTelemetry（EDOT）、Kubernetes（ECK）、故障排除手冊與 9.x 版本演進等章節。完整差異見 附錄 D 版本紀錄，查證依據見 附錄 E 查證紀錄。 ...

Prometheus與Grafana教學手冊 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 版本基準 Prometheus 3.15.0（2026-09-24）、Prometheus LTS 3.13.x（支援至 2027-07-31）、Alertmanager 0.34.1、Grafana 13.2.3（2026-09-29）、node_exporter 1.12.1；完整矩陣見 1.5 版本基準與相容性矩陣 文件定位 企業標準技術白皮書／內部標準教材：Prometheus＋Alertmanager＋Grafana 的規劃、安裝、設定、使用、告警、安全、高可用、維運與升級 適用對象 資深工程師、DevOps／SRE、系統管理員、系統架構師、資安與稽核人員 前置知識 Linux 系統管理（systemd、防火牆、檔案權限）、容器與 Kubernetes 基本概念、HTTP 與 TLS、YAML 姊妹文件 《Metrics Visualization 教學手冊》：指標設計、PromQL 分析、儀表板設計、SLO 與架構決策的深入探討；《OpenTelemetry教學手冊》：OTel SDK 與 Collector；《Logs Visualization 教學手冊》：日誌視覺化 前一版本 1.0（2026-01-27，以 Prometheus 2.48、Grafana 10.2 為基準） Created by Eric Cheng 📌 v2.0 改版重點：章節重新編排為 15 章與 7 個附錄，全面對齊 Prometheus 3.x、Alertmanager 0.34 與 Grafana 13。 修正錯誤：修正 v1.0 中已不適用或會造成故障的內容。例如 3.x 發行包已不含 consoles、apt-key 已棄用、Alertmanager /api/v1 已移除（回傳 410）、match／source_match 已棄用、Teams Office 365 connector 已停用、快照還原步驟會刪除快照本身、儲存估算重複折算壓縮率、Grafana 稽核設定鍵錯誤且為 Enterprise 限定、Istio istio-telemetry 已不存在等。 新增內容：容量規劃、Alertmanager 安裝、Compose 與 Kubernetes 部署、離線安裝、Service Discovery 與 relabel、抓取保護、Remote Write／Agent mode、OTLP、Grafana 資料庫與認證整合、原生直方圖、Dynamic dashboards、Grafana Alerting 決策、規則單元測試、安全強化、高可用、自我監控、Prometheus 2.x → 3.x 遷移、Grafana 13 升級、AI 輔助維運與臺灣法規對應。 追溯依據：所有差異見 E.2 v1.0 → v2.0 更正對照表，查證依據見 附錄 F：查證紀錄。 閱讀指引 讀者角色 建議閱讀章節 初次接觸 Prometheus／Grafana 第 1 章 → 第 2 章 → 4.5 → 第 7 章 → 第 8 章 系統管理員（VM／實體機） 第 3 章 → 4.1–4.4 → 第 5、6 章 → 第 12 章 → 第 13 章 Kubernetes 平台工程師 2.6 → 4.6 → 5.2–5.4 → 11.1–11.2 → 12.4 SRE／值班人員 第 7 章 → 第 9 章 → 12.1 → 12.6 → 第 15 章 應用程式開發人員 2.2–2.3 → 7.4 → 14.1–14.2 → 14.5 架構師 2.6–2.7 → 3.2 → 第 11 章 → 14.3–14.4 資安／稽核人員 第 10 章 → 14.6 → 15.3 技術主管／決策者 1.1–1.5 → 2.7 → 13.1 → 14.6 → 14.7 本文慣例 標記 意義 ✅／❌ 建議做法／不建議做法 ⚠️ 容易出錯或有風險的地方 💡 實務技巧 🧪 實驗性功能：需 --enable-feature 或 feature toggle，行為可能在後續版本變更，不納入 LTS 支援範圍 📌 版本差異或改版說明 🏢 只在 Grafana Enterprise 或 Grafana Cloud 提供的功能 $變數 Grafana 範本變數 <尖括號> 需依環境替換的值 example.internal 範例內部網域，請替換為實際網域 ⚠️ 本手冊的指令以 RHEL 9／10 與 Ubuntu 24.04 LTS 為例，設定檔與 PromQL 皆以 Prometheus 3.15、Alertmanager 0.34.1、Grafana 13.2.3 撰寫，並以官方二進位檔的 promtool／amtool 驗證（見 附錄 F：查證紀錄）。若仍在 Prometheus 2.x，請先閱讀 13.2 Prometheus 2.x → 3.x 遷移。 ...

Logs Visualization 教學手冊（ELK Stack） 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 版本基準 Elastic Stack 9.5.4（2026-09-15 發佈）：Elasticsearch／Logstash／Kibana 同版；相容說明涵蓋 8.19.x（支援至 2027-07-15） 文件定位 企業標準技術白皮書／內部標準教材：Logs 視覺化、查詢分析、告警與治理 適用對象 資深軟體工程師、系統架構師、SRE／DevOps 工程師、資安與稽核人員 前置知識 Linux 基礎、Java／Spring Boot 應用程式、JSON 與 HTTP API、基本的 Elasticsearch 概念 姊妹文件 《ELK Stack 教學手冊》v2.0：平台安裝、設定、升級、ECK、叢集維運 前一版本 1.0（2026-01-26，以 Elastic Stack 8.x 早期做法為主） Created by Eric Cheng 📌 v2.0 改版重點：全面對齊 Elastic Stack 9.5。索引設計從「每日 index ＋ rollover alias」改為 Data Stream ＋ ECS ＋ LogsDB。Logstash 範例改用 ssl_enabled、API Key 與 data stream 輸出。修正 v1.0 中已失效或錯誤的設定，例如 ILM freeze、node.attr.data、Alerting 規則格式、grok 自訂 pattern 錯誤、萬用字元刪除 index、法規年限等。新增多個章節：ES|QL、Log 分析（Pattern／Rate／Change Point）、Dashboard as Code、Elastic AI（Agent Builder、MCP）、AI 治理、查詢問題排除、導入路線圖、上線審查清單。完整差異見 D.2 v1.0 → v2.0 更正對照表，查證依據見 附錄 E：查證紀錄。 ...

Metrics Visualization 教學手冊（Prometheus + Grafana） 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 版本基準 Prometheus 3.15.0（2026-09-24）、Prometheus LTS 3.13.x（支援至 2027-07-31）、Grafana 13.2.3（2026-09-29）、Alertmanager 0.34.1；完整矩陣見 1.3 版本基準與相容性矩陣 文件定位 企業標準技術白皮書／內部標準教材：指標設計、PromQL 分析、儀表板、告警與 SLO、架構決策與治理 適用對象 資深後端工程師、系統架構師、SRE／DevOps 工程師、技術主管、資安與稽核人員 前置知識 Linux 與容器、Kubernetes 基本概念、RESTful API、微服務架構、基本監控概念 姊妹文件 《Prometheus與Grafana教學手冊》：安裝、設定檔、維護、升級操作步驟；《OpenTelemetry教學手冊》：OTel SDK 與 Collector 前一版本 1.0（2026-01-26，以 Prometheus 2.x／Grafana 11 時期做法為主） Created by Eric Cheng 📌 v2.0 改版重點：全面對齊 Prometheus 3.x 與 Grafana 13。修正 v1.0 中無法執行或結果錯誤的範例，例如 relabel 位址改寫、predict_linear 子查詢語法、錯誤率告警百分比顯示、不存在的指標名稱 redis_keys_total、Pushgateway「TTL」說法、以「P99 達標時間比例」定義延遲 SLO 等。新增原生直方圖、OTLP 與 UTF-8、Kubernetes Operator、Alertmanager 設計、規則單元測試、Dynamic dashboards、Dashboard as Code（Git Sync）、Grafana Alerting、多視窗多燃燒率告警、SLO 工具鏈、Grafana Assistant 與 MCP、AI 治理，以及第 9 章「企業級部署、容量與治理」。完整差異見 D.2 v1.0 → v2.0 更正對照表，查證依據見 附錄 E：查證紀錄。 ...

微前端教學手冊 版本：1.0 最後更新：2026 年 1 月 適用對象：資深工程師 / Tech Lead / Architect 最後更新: 2026年1月23日 適用於: 微前端 Created by: Eric Cheng 微前端（Micro-Frontend）教學手冊 版本：1.0 適用對象：資深前端/全端工程師、Tech Lead、架構師 最後更新：2026 年 1 月 目錄 微前端的核心價值與真正要解決的問題 1.1 什麼是微前端？ 1.2 微前端真正要解決的問題 1.3 什麼情況「不該用微前端」 1.4 微前端 vs 單體前端 vs Monorepo 1.5 本章實務案例 微前端主流架構模式比較 2.1 基座（Shell / Container）模式 2.2 Runtime Integration vs Build-time Integration 2.3 iframe / Web Components / Module Federation 比較 2.4 主流框架方案比較 2.5 本章實務案例 Module Federation 深度解析 ...

Claude Agent Skills 使用教學手冊 版本：1.0 最後更新：2026 年 1 月 適用對象：新進軟體工程師、系統分析師、AI 導入成員 最後更新: 2026年1月8日 適用於: Claude Code Created by: Eric Cheng 目錄 前言 文件目的 適用對象 如何使用本手冊 第一章：Claude Agent 與 Agent Skills 基礎概念 1.1 什麼是 Claude Agent 1.2 什麼是 Agent Skills 1.3 Agent / Tool / Skill 的差異與關係 1.4 為什麼要使用 Agent Skills 第二章：Agent Skills 的設計理念 2.1 Skill 的責任邊界（Single Responsibility） 2.2 Skill 與 Prompt 的差異 2.3 Skill 是可重用、可組合的能力單元 2.4 官方 Skills Repo 的設計原則 第三章：官方 Skills Repository 結構說明 3.1 Skills GitHub 專案的目錄結構 3.2 Skill 的命名慣例 3.3 Skill 定義中的關鍵元素 第四章：Agent Skills 的使用方式 4.1 如何在 Agent 中呼叫 Skill 4.2 Skill 在任務流程中的角色 4.3 單一 Skill vs 多 Skill 組合 第五章：實務範例 5.1 需求文件產生 Skill 5.2 程式碼 Review / 重構 Skill 5.3 測試案例產生 Skill 第六章：新手常見錯誤與最佳實務 6.1 Skill 設計過大或過小的問題 6.2 把 Skill 當成一次性 Prompt 的錯誤用法 6.3 如何讓 Skill 更容易被重用 6.4 如何讓 Agent 行為更穩定 第七章：團隊導入建議 7.1 適合先從哪些類型的 Skill 開始 7.2 如何建立內部 Skill Library 7.3 與既有開發流程整合 7.4 導入成熟度階段建議 附錄：檢查清單（Checklist） Skill 建立前檢查 SKILL.md 撰寫檢查 Skill 發布前檢查 團隊導入檢查 參考資源 官方資源 延伸閱讀 前言 文件目的 本手冊旨在協助團隊成員快速理解並導入 Claude Agent Skills，透過系統化的教學內容，讓新進同仁能夠： ...

文件版本：2.0 對應規範：MCP Specification 2026-07-28（正式版，2026-07-28 發布） 前一規範：2025-11-25（相容性內容仍保留於本文） 最後更新：2026 年 7 月 31 日 文件等級：企業標準技術白皮書 適用對象：資深軟體開發工程師、系統架構師、平台工程與資安治理人員 Created by：Eric Cheng Anthropic Model Context Protocol (MCP) 教學手冊 重大提醒：2026-07-28 是 MCP 自發布以來最大幅度的改版，包含破壞性變更（Breaking Changes）。 核心協議由「有狀態、雙向」轉為「無狀態、請求／回應」。initialize 交握、Mcp-Session-Id 與 SSE 續傳機制均已移除；Roots、Sampling、Logging 進入棄用（Deprecated）狀態。 詳見 版本更新摘要 與 第十一章。 目錄 版本更新摘要：2026-07-28 規範重點 0.1 一頁式變更總覽 0.2 破壞性變更清單 0.3 棄用功能與生命週期政策 0.4 本手冊改版說明 第一章：MCP 概述與核心概念 1.1 什麼是 MCP？ 1.2 為什麼需要 MCP？ 1.3 MCP 架構概覽 1.4 協議演進史與版本治理 第二章：MCP 技術架構深度解析 2.1 分層架構 2.2 資料層協議（Data Layer Protocol） 2.3 MCP 核心原語（Primitives） 2.4 通知機制與訂閱串流（Notifications & Subscriptions） 2.5 多輪往返請求（Multi Round-Trip Requests, MRTR） 第三章：傳輸層深度解析 3.1 STDIO Transport 3.2 Streamable HTTP Transport 3.3 標頭路由、快取與可觀測性 3.4 傳輸層相容性策略 第四章：實戰開發指南 4.1 開發環境設置 4.2 開發 MCP Server 4.3 開發 MCP Client 4.4 整合到 AI 應用 第五章：完整實戰範例 5.1 範例一：檔案系統 MCP Server 5.2 範例二：資料庫查詢 MCP Server 5.3 範例三：API 整合 MCP Server 第六章：最佳實踐與設計模式 6.1 MCP Server 設計原則 6.2 效能優化 6.3 安全性考量 6.4 測試策略 第七章：進階主題 7.1 Tasks 擴充（io.modelcontextprotocol/tasks） 7.2 自訂傳輸層 7.3 多語言 SDK 比較 7.4 偵錯與監控 第八章：疑難排解 8.1 常見錯誤與解決方案 8.2 除錯技巧 8.3 錯誤訊息參考 第九章：實際案例研究 9.1 案例一：企業知識庫 MCP Server 9.2 案例二：DevOps 整合 MCP Server 第十章：資源與參考 10.1 官方資源 10.2 社群資源 10.3 開發環境建議 10.4 版本相容性 10.5 快速參考 第十一章：2026-07-28 遷移指南 11.1 遷移總體策略 11.2 Server 端遷移步驟 11.3 Client 端遷移步驟 11.4 從 Session 到顯式握柄（Explicit Handle） 11.5 雙時代（Dual-era）相容部署 第十二章：擴充框架與官方擴充 12.1 擴充框架（Extensions Framework） 12.2 MCP Apps：伺服器渲染互動介面 12.3 Tasks 擴充深入解析 12.4 企業託管授權（EMA）與 OAuth 擴充 12.5 自建第三方擴充 第十三章：企業級部署與治理 13.1 無狀態水平擴展架構 13.2 API 閘道、WAF 與速率限制 13.3 授權硬化與身分治理 13.4 可觀測性與 OpenTelemetry 13.5 一致性驗證與 SDK 分級 附錄：檢查清單（Checklist） A. Server 開發檢查清單 B. 部署檢查清單 C. 程式碼審查檢查清單 D. 故障排除檢查清單 E. 2026-07-28 遷移檢查清單 結語 參考文獻與延伸閱讀 官方規範（2026-07-28） 治理與流程 官方擴充 官方部落格 社群分析 相關標準 主要 SEP 索引 版本更新摘要：2026-07-28 規範重點 0.1 一頁式變更總覽 2026-07-28 由六份以上的 SEP（Specification Enhancement Proposal）共同構成，將 MCP 從 「為單機 stdio 情境設計的有狀態雙向協議」重塑為「可在通用 HTTP 基礎設施上水平擴展的無狀態 請求／回應協議」。以下為與前一版 2025-11-25 的對照總覽。 ...