Herdr 教學手冊

Herdr —— 企業級 AI Coding Agent Runtime / Multi-Agent Workspace 完整導入指南 適用對象：資深 Software Architect、SA、Backend/Frontend Engineer、AI Agent 平台團隊、DevSecOps、Tech Lead、PM/PG/QA、企業導入負責人 文件性質：企業內部「Herdr + AI Coding Agent（Claude Code／GitHub Copilot CLI／Codex）」導入、開發與維運培訓教材 版本基準：herdrdev/herdr（Apache License 2.0，於 v0.8.0／2026-08-03 relicense 自 AGPL-3.0-or-later），最新 Stable Release v0.8.2（2026-08-19） 　　　　　官方文件基準：herdr.dev/docs/* 全部 20 個頁面（Install、Quick Start、Concepts、Agents、Integrations、Agent Automation、Agent Skill、Session State、Persistence & Remote、How to Work、Configuration、Config Reference、Keyboard、CLI Reference、Socket API、Plugins、Marketplace、Troubleshooting、Windows、Compare） 查證日期：2026-09-06（初版 2026-08-12，本次為 v0.8.2 版本複查；異動對照見 Appendix G） 技術堆疊：Rust 單一執行檔（Server + Client）、TOML 設定檔、本機 Socket API（Unix Domain Socket／Windows Named Pipe）

⚠️ 重要聲明（請務必先讀）

1. Herdr 仍在快速迭代中。 這是一個活躍開發、Release 節奏頻繁（v0.7.0 → v0.8.0 期間多次 preview 版本）的開源專案，CLI 指令、Socket API method、設定鍵、Agent 偵測清單都可能隨版本演進調整。任何指令、設定、路徑、支援的 Agent 清單，在正式導入前，務必以官方最新 github.com/herdrdev/herdr 之 README.md／CHANGELOG.md／herdr.dev/docs/ 與你實際安裝的版本為準。

2. 本手冊是彙整、重組、補充企業導入實務，而不是官方文件的翻譯。 本書不逐字翻譯官方 README 或 docs 站內容，而是依官方原始碼與官方文件重新查證後，以繁體中文重新組織，並大量補充 Scenario／Example、比較表、Checklist、企業導入建議與 AI Agent Prompt 範本。

3. 本手冊採用五層 Provenance 標示，請務必先理解這套標示法，它貫穿全書每一個具體事實與主張：

   標示	意義	使用時機
   官方已實作	GitHub README／CHANGELOG／herdr.dev/docs 明確確認已出貨的功能	有明確官方文件出處可查
   Source-confirmed	只能從官方原始碼／設定檔確認，官方文件未明確著墨	本手冊研究團隊直接讀取原始碼或官方 docs 站原始檔得到的事實
   Roadmap/Issue（規劃中）	官方 Roadmap 或 Issue/PR 討論中，尚未 merge/發布	用於區分「已規劃」與「已出貨」，避免混淆
   建議架構	本手冊作者針對企業導入的建議，非官方功能	用於企業落地建議、原創比較表、原創案例、Workspace 命名規範等
   推測/Hypothesis	無法從任何層級來源確認，僅為合理推論	用於誠實標示研究缺口，提醒讀者自行查證

   凡是標成「建議架構」或「推測/Hypothesis」的內容，都不是 Herdr 的官方功能，請勿在企業內部溝通或對外簡報時誤植為官方保證。

4. 一個必須從第一頁就知道的定位澄清：Herdr 不是 AI Model、不是 IDE、不是 完整 Agent Orchestrator、不是 CI/CD Platform、不是 Kubernetes、不是 完整 Observability Platform。它是「AI Coding Agent 長時間運作所需要的 Terminal Runtime + Workspace 管理層」。第 2 章與第 55 章會反覆界定這個範圍，避免過度宣稱。

5. Windows 支援現況聲明（本次複查最重要的異動）：截至查證日期（2026-09-06），Herdr 的原生 Windows 版本已於 v0.8.2（2026-08-19）轉為正式支援（General Availability），Stable 成為 Windows 的預設更新通道（官方已實作，Windows 文件／v0.8.2 Release Notes）。這推翻了本手冊初版（2026-08-12 基準）「Windows 為 preview-only beta」的描述，若你手上有本手冊的舊版本，第 8 章請以本版為準。

   但「GA」不等於「功能與 Linux/macOS 對等」。官方仍明列數項原生 Windows 不支援的功能，其中對企業架構決策影響最大的是：Direct Terminal Attach、Live Server Handoff、以及不能作為 herdr --remote 的被連線目標主機。完整清單與中性的「原生 Windows vs WSL2」決策矩陣見第 8.3～8.4 節。本手冊不再以「Preview 不穩定」作為建議 WSL2 的理由，改以「你的流程是否用到上述缺口功能」作為判準。

6. 銀行/企業案例聲明：本手冊中出現的銀行/金融業案例（例如 Web Application 開發實戰、逆向工程、Framework Upgrade 案例中的 bank-web-platform、PaymentController 等）均為教學示範用途之虛構情境，用於示範 Herdr 承載 AI Coding Agent 工作流程的方式，並非真實客戶專案。涉及既有框架的深入機制，請參閱本 Repository 既有手冊：

   • Spring boot 4.x 教學手冊
   • Vue3 前端framework教學
   • PrimeVue使用教學
   • Java25升版教學

7. Apache License 2.0 授權範圍聲明：Herdr 採 Apache License 2.0（2026-08-03 v0.8.0 relicense 自 AGPL-3.0-or-later），本手冊對授權條款的說明僅供參考，實際權利義務請以官方 LICENSE 檔案逐字內容為準，本手冊不構成法律意見。

8. 官方權威來源與研究來源分級，請見 Appendix E（Official References）與 Appendix F（Research Sources）。

符號約定

Provenance 五層標示

本文以括號文字直接標示於句末，例如「…（官方已實作，Install 文件）」或「…（建議架構）」。標示意義同上表，全書一致使用，不再重複解釋。

Mermaid 圖表慣例

• 所有架構圖、流程圖、序列圖均以 Mermaid 語法呈現，可直接在支援 Mermaid 的 Markdown 檢視器（GitHub、VS Code 外掛等）中渲染。
• 節點標籤若包含括號、冒號、斜線等特殊字元，一律以雙引號包住整個標籤（例如 A["Agent State (blocked)"]），避免解析錯誤。
• 實線箭頭代表已從官方原始碼或官方文件確認的關係（Source-confirmed／官方已實作）；虛線箭頭代表依現有事實合理推論、但官方未逐一列點確認的路徑（建議架構），圖說明會另外標註。

程式碼區塊慣例

• 標示為「示意」或「非逐字官方指令」的程式碼區塊，是本手冊為了幫助理解而重新撰寫的概念示範，不是官方指令的逐字引用，不可直接複製貼上當作生產環境操作。
• 未標示「示意」的指令（例如安裝指令、CLI 指令）為官方文件或原始碼中可查證的真實指令；如該指令僅適用特定平台/安裝方式，會在指令上方明確標註（例如「Linux/macOS」「Windows Preview」）。

章節固定小節

重要章節盡量包含以下小節：Scenario／Example（具體案例）、AI Prompt 範例、本章 Checklist 與小結。

版本與相容性速查表

以下目錄為可點擊錨點連結，可直接跳轉至本文對應章節。TOC-AUTO 標記之間的內容需與內文標題保持一致，修改章節標題後請一併更新此區塊，並以本 Repository 根目錄的 check-toc.ps1 驗證錨點正確性（./check-toc.ps1 -Path <本檔路徑>，三類問題皆應回報「無」）；Markdown 格式則以 check-md.ps1 驗證。

目錄（Table of Contents）

• 1. 文件說明
  • 1.1 這份手冊要解決什麼問題
  • 1.2 如何閱讀這份手冊
  • 1.3 與其他手冊的差異
  • 1.4 本章 Checklist 與小結
• 2. Herdr 簡介與定位
  • 2.1 Herdr 是什麼
  • 2.2 Herdr 不只是這些
  • 2.3 Herdr 在 AI Software Development Lifecycle 中的位置
  • 2.4 Herdr 是否等於 Agent？是否取代 Claude Code / Codex / Copilot？
  • 2.5 Herdr 與 IDE、Agent Orchestrator 的關係
  • 2.6 Herdr 的核心價值（企業視角）
  • 2.7 AI Prompt 範例
  • 2.8 本章 Checklist 與小結
• 3. 為什麼企業需要 Herdr
  • 3.1 傳統 AI Coding Workflow 的真實痛點
  • 3.2 Herdr 如何改善
  • 3.3 Scenario：一位資深工程師的一天
  • 3.4 本章 Checklist 與小結
• 4. Herdr 核心概念
  • 4.1 六大核心概念
  • 4.2 概念階層圖
  • 4.3 ID 命名規則實例
  • 4.4 Server／Client 分離的意義
  • 4.5 Scenario：一個中型 Web 專案的 Workspace 規劃
  • 4.6 AI Prompt 範例
  • 4.7 本章 Checklist 與小結
• 5. Herdr 系統架構
  • 5.1 架構總覽
  • 5.2 Process Lifecycle
  • 5.3 Session Persistence 與 Terminal Persistence
  • 5.4 Detach / Attach
  • 5.5 Agent Detection：兩層機制
  • 5.6 Client/Server 分離、Local 與 Remote 執行
  • 5.7 Scenario：架構師評估導入風險
  • 5.8 AI Prompt 範例
  • 5.9 本章 Checklist 與小結
• 6. Herdr 與 tmux／zellij／IDE／Agent Orchestrator 比較
  • 6.1 完整比較表
  • 6.2 為什麼不應該只把 Herdr 當成 tmux replacement
  • 6.3 Herdr 與 Agent Orchestrator 的界線
  • 6.4 Scenario：架構師選型會議
  • 6.5 本章 Checklist 與小結
• 7. 安裝環境：Linux／macOS
  • 7.1 系統需求
  • 7.2 安裝方式
  • 7.3 PATH 設定
  • 7.4 驗證安裝
  • 7.5 啟動
  • 7.6 本章 Checklist 與小結
• 8. 安裝環境：Windows
  • 8.1 Windows 支援現況：正式支援（GA）
  • 8.2 安裝方式（Windows）
  • 8.3 已知限制
  • 8.4 Windows 原生 vs WSL2 Linux 的分析建議
  • 8.5 Scenario：企業 Windows 開發機導入評估
  • 8.6 本章 Checklist 與小結
  • 8.7 v0.8.2 的 Windows 相關新增能力
• 9. 安裝驗證與 Installation Checklist
  • 9.1 驗證指令
  • 9.2 常見安裝後檢查項目
  • 9.3 Installation Checklist
  • 9.4 常見錯誤（安裝階段）
• 10. Herdr Quick Start
  • 10.1 十步驟從零開始
  • 10.2 Troubleshooting（Quick Start 階段）
  • 10.3 本章 Checklist 與小結
• 11. Keyboard／Mouse 操作
  • 11.1 三種操作模式
  • 11.2 常用鍵盤操作（預設鍵位）
  • 11.3 Copy Mode 內操作
  • 11.4 滑鼠操作
  • 11.5 Scenario：鍵盤 vs 滑鼠的團隊規範
  • 11.6 本章 Checklist 與小結
  • 11.7 v0.8.2 鍵盤／滑鼠新增能力
• 12. Workspace 設計（企業級規範）
  • 12.1 企業級 Workspace 命名與分層原則（建議架構）
  • 12.2 範例一：企業 Web Application Workspace
  • 12.3 範例二：以角色分層的 Workspace
  • 12.4 何時該用哪種模式
  • 12.5 Scenario：從單人開發擴展到團隊協作
  • 12.6 AI Prompt 範例
  • 12.7 本章 Checklist 與小結
• 13. Claude Code + Herdr 實戰
  • 13.1 啟動與基本操作
  • 13.2 如何保持 Session
  • 13.3 如何觀察狀態
  • 13.4 如何重新 Attach
  • 13.5 如何處理 Blocked
  • 13.6 如何避免多個 Claude Code 修改同一份程式碼造成衝突
  • 13.7 Scenario：一人多 Claude Code 分工
  • 13.8 AI Prompt 範例（Backend Agent，供 Claude Code 使用）
  • 13.9 本章 Checklist 與小結
• 14. GitHub Copilot CLI + Herdr 實戰
  • 14.1 基本流程
  • 14.2 與 Claude Code／Codex 共存
  • 14.3 Scenario：測試補強分工
  • 14.4 AI Prompt 範例（Test Agent，供 Copilot CLI 使用）
  • 14.5 本章 Checklist 與小結
• 15. Codex + Herdr 實戰
  • 15.1 基本流程
  • 15.2 與其他 Agent 分工
  • 15.3 Scenario：Issue 導向修復
  • 15.4 AI Prompt 範例（Frontend Agent，供 Codex 使用）
  • 15.5 本章 Checklist 與小結
• 16. Multi-Agent Software Development
  • 16.1 總覽圖
  • 16.2 Pattern A：Parallel（平行分工）
  • 16.3 Pattern B：Sequential（序列接力）
  • 16.4 Pattern C：Reviewer（交叉驗證）
  • 16.5 Pattern D：Research + Implementation（研究先行）
  • 16.6 四種模式比較
  • 16.7 Scenario：混合模式的真實案例
  • 16.8 本章 Checklist 與小結
• 17. Web Application 開發實戰
  • 17.1 技術 Stack 與 Herdr 的關係
  • 17.2 開發流程中 Herdr 的角色
  • 17.3 Scenario：一個 Sprint 的實際運作
  • 17.4 AI Prompt 範例（Architecture Agent）
  • 17.5 本章 Checklist 與小結
• 18. Web Application Multi-Agent Workspace 範例
  • 18.1 完整範例
  • 18.2 使用建議
  • 18.3 本章 Checklist 與小結
• 19. 逆向工程 Software Development
  • 19.1 整體流程
  • 19.2 逆向工程十四步驟
  • 19.3 Agent 分工與 Workspace 配置
  • 19.4 人類審查點與 Git 分支策略
  • 19.5 AI Prompt 範例（Reverse Engineering Agent）
  • 19.6 本章 Checklist 與小結
• 20. Framework Upgrade
  • 20.1 案例背景
  • 20.2 Agent 分工流程
  • 20.3 Herdr 如何讓這些 Agent 長時間並行或序列執行
  • 20.4 Scenario：Spring Boot 3.x → 4.x 升級
  • 20.5 本章 Checklist 與小結
• 21. Framework Upgrade Agent Workflow
  • 21.1 十二階段總覽
  • 21.2 Scenario：以 Herdr Tab 對應 Phase 進度
  • 21.3 本章 Checklist 與小結
• 22. AI Agent Blocked State 深入解析
  • 22.1 Agent 卡住不等於 Agent 崩潰
  • 22.2 常見 Blocked 原因
  • 22.3 狀態決策圖
  • 22.4 團隊 SOP
  • 22.5 本章 Checklist 與小結
• 23. Herdr + Git
  • 23.1 Multi-Agent 的 Git 分支規範
  • 23.2 Branch／Commit／Diff／Merge／Review／Rollback 搭配 Herdr
  • 23.3 本章 Checklist 與小結
• 24. Herdr + Git Worktree + Multi-Agent
  • 24.1 進階架構
  • 24.2 為什麼 Worktree 架構比共用 Working Directory 更安全
  • 24.3 Scenario：實務操作示意
  • 24.4 本章 Checklist 與小結
• 25. Remote Development
  • 25.1 Herdr 與 SSH 的使用方式
  • 25.2 斷線與恢復情境
  • 25.3 具名 Session（Named Sessions）
  • 25.4 Remote Attach：平台支援矩陣與設定
  • 25.5 Direct Terminal Attach 與 Bridge API
  • 25.6 適合企業 Server／Dev VM／Cloud VM 的情境
  • 25.7 本章 Checklist 與小結
• 26. Herdr API／Automation
  • 26.1 三層整合介面
  • 26.2 三個自動化原語（Primitive）
  • 26.3 Agent 身分、啟動與控制介面
  • 26.4 Agent Skill：讓 Agent 自己操作 Herdr
  • 26.5 實際可用範例
  • 26.6 Socket API 傳輸格式
  • 26.7 目前版本不提供 / 尚未確認支援
  • 26.8 本章 Checklist 與小結
• 27. Agent-to-Agent Automation
  • 27.1 概念示意
  • 27.2 三個層次的清楚區分
  • 27.3 不要把 Herdr 描述成完整 Multi-Agent Orchestrator
  • 27.4 AI Prompt 範例（供人類撰寫串接腳本時參考的需求描述）
  • 27.5 本章 Checklist 與小結
• 28. Plugin Architecture
  • 28.1 Plugin 基本結構
  • 28.2 Manifest 欄位
  • 28.3 安裝與管理
  • 28.4 Marketplace
  • 28.5 企業內部 Plugin 可能用途（建議架構）
  • 28.6 本章 Checklist 與小結
  • 28.7 Plugin 執行環境與管理指令補充
    • 28.7.1 注入的環境變數
    • 28.7.2 Startup Hook 的正確語意
    • 28.7.3 Pane 放置位置與 id 命名限制
    • 28.7.4 完整管理指令
    • 28.7.5 Marketplace 的實際運作機制
• 29. Agent Integration 深度
  • 29.1 三種整合深度比較
  • 29.2 為什麼 Agent Integration 越深，Herdr 越能正確理解 Agent Lifecycle
  • 29.3 以 Claude Code／Codex／GitHub Copilot CLI 為例
  • 29.4 自建/客製 Agent 的整合方式
  • 29.5 本章 Checklist 與小結
• 30. Herdr Configuration
  • 30.1 設定檔位置與格式
  • 30.2 常用操作
  • 30.3 常見設定區塊（示意）
  • 30.4 本章 Checklist 與小結
  • 30.5 config.toml 主要區塊一覽
• 31. 系統維護 SOP
  • 31.1 維運週期總覽
  • 31.2 Session Cleanup
  • 31.3 Process／磁碟檢查（建議架構，搭配作業系統既有工具）
  • 31.4 Workspace／Agent／Plugin 清理
  • 31.5 本章 Checklist 與小結
• 32. Herdr 升級
  • 32.1 herdr update
  • 32.2 Stable／Preview Channel
  • 32.3 不同安裝方式的更新策略比較
  • 32.4 Server/Client 相容性與 Live Handoff
  • 32.5 Upgrade SOP Checklist
  • 32.6 本章 Checklist 與小結
• 33. Backup／Recovery
  • 33.1 需要備份的項目
  • 33.2 最重要的觀念：Session Recovery ≠ Code Recovery
  • 33.3 本章 Checklist 與小結
• 34. Security
  • 34.1 風險分析
  • 34.2 風險項目清單
  • 34.3 AI Coding Agent + Herdr Security Checklist
  • 34.4 本章 Checklist 與小結
• 35. Banking／Enterprise Environment
  • 35.1 典型企業/銀行網路拓樸
  • 35.2 需考量的企業限制
  • 35.3 本章 Checklist 與小結
• 36. AI Coding Governance
  • 36.1 治理流程
  • 36.2 禁止事項
  • 36.3 本章 Checklist 與小結
• 37. SSDLC + Herdr
  • 37.1 各階段配置 Agent
  • 37.2 Herdr 在其中負責什麼
  • 37.3 本章 Checklist 與小結
• 38. Spec-Driven Development + Herdr
  • 38.1 架構
  • 38.2 Herdr 如何成為 Agent Runtime Layer
  • 38.3 本章 Checklist 與小結
• 39. Loop Engineering + Herdr
  • 39.1 循環流程
  • 39.2 Herdr 如何提供長時間執行環境
  • 39.3 本章 Checklist 與小結
• 40. AI Agent Team Blueprint
  • 40.1 企業級 AI Development Team 設計
  • 40.2 使用 Herdr 建立對應 Workspace
  • 40.3 本章 Checklist 與小結
• 41. PM／SA／Architect／SD／PG／QA／DevOps／Security 使用方式
  • 41.1 本章 Checklist 與小結
• 42. Team Operating Model
  • Rule 1：一個 Agent 一個明確責任
  • Rule 2：一個 Workspace 對應一個 Project
  • Rule 3：重大修改一定建立 Git Checkpoint
  • Rule 4：Agent 不可直接覆蓋其他 Agent 的工作
  • Rule 5：Blocked Agent 必須有人處理
  • Rule 6：AI Agent 不可直接進 Production
  • Rule 7：所有 AI 產生的重大程式碼必須經過 Test + Review
  • 42.1 本章 Checklist 與小結
• 43. 常見錯誤
• 44. Troubleshooting Decision Tree
  • 44.1 官方 Troubleshooting 頁面對照
  • 44.2 本章 Checklist 與小結
• 45. 效能與資源管理
  • 45.1 需要關注的資源面向
  • 45.2 Multi-Agent 數量如何規劃
  • 45.3 Scenario：資源規劃實務
  • 45.4 v0.8.2 對資源規劃的兩項影響
  • 45.5 本章 Checklist 與小結
• 46. 可觀測性
  • 46.1 可觀測的狀態面向
  • 46.2 Herdr 狀態資訊 vs 完整 Observability Platform
  • 46.3 本章 Checklist 與小結
• 47. 企業導入架構與 Enterprise Rollout Plan
  • 47.1 企業導入架構
  • 47.2 Enterprise Rollout 五階段
  • 47.3 本章 Checklist 與小結
• 48. KPI
  • 48.1 建議 KPI 清單
  • 48.2 為什麼避免只用「AI 寫了多少行程式碼」
  • 48.3 本章 Checklist 與小結
• 49. Herdr 導入建議
  • 適合使用
  • 不適合使用
  • 必須搭配
  • 不應該做的事情
  • POC 建議
  • Production／企業建議
  • Enterprise Governance 建議
  • 49.1 本章 Checklist 與小結
• 50. 最終企業標準 SOP
  • 50.1 本章 Checklist 與小結
• 51. Cheat Sheet
  • 51.1 本章 Checklist 與小結
• 52. AI Agent Prompt 範本
  • Architecture Agent Prompt
  • Reverse Engineering Agent Prompt
  • Frontend Agent Prompt
  • Backend Agent Prompt
  • Database Agent Prompt
  • Test Agent Prompt
  • Security Agent Prompt
  • Code Review Agent Prompt
  • Framework Migration Agent Prompt
  • Documentation Agent Prompt
  • DevOps Agent Prompt
  • 52.1 本章 Checklist 與小結
• 53. Herdr Agent Team 完整範例
  • 53.1 案例目標
  • 53.2 Workspace 配置
  • 53.3 端到端流程說明
  • 53.4 本章 Checklist 與小結
• 54. 最佳實務總結
  • Top 10 Herdr Best Practices
  • Top 10 Mistakes
  • Top 10 Enterprise Recommendations
• 55. 架構師最終評估
  • Herdr 解決什麼問題？
  • Herdr 沒有解決什麼問題？
  • Herdr 與 Agent Framework 的界線？
  • Herdr 與 Agent Orchestrator 的界線？
  • Herdr 與 IDE 的界線？
  • Herdr 與 tmux 的界線？
  • Herdr 是否適合 Enterprise？
  • Herdr 是否適合 Banking？
  • Herdr 是否適合 Legacy Modernization？
  • Herdr 是否適合 Framework Migration？
  • Herdr 是否適合 Multi-Agent Development？
  • Architecture Recommendation
  • 55.1 本章 Checklist 與小結
• 56. 結語
• Appendix A：Command Reference
• Appendix B：Configuration Reference
• Appendix C：Architecture Diagrams 索引
• Appendix D：Glossary
• Appendix E：Official References
• Appendix F：Research Sources
• Appendix G：版本異動對照（v0.8.0 → v0.8.2）
  • G.1 讀者層級的 Breaking Change（必讀）
  • G.2 v0.8.2（2026-08-19）主要異動
  • G.3 v0.8.1 說明
  • G.4 本手冊本次的自我更正

1. 文件說明

1.1 這份手冊要解決什麼問題

企業導入 AI Coding Agent（Claude Code、GitHub Copilot CLI、Codex 等）時，最常見的落地障礙不是「Agent 不夠聰明」，而是沒有一個能讓 Agent 長時間、可觀察、可恢復地運作的執行環境。開發者常見的作法是同時打開 5、6 個終端機視窗，分別跑不同 Agent、build、test、git，一旦 SSH 斷線或筆電關機，所有進度就中斷。Herdr 定位為解決這個「Agent Runtime」層問題的工具（官方已實作，README：「the runtime your coding agents live on」）。

本手冊的目標，是把 Herdr 的官方能力，重新組織成一份可以直接用於：

• 個人開發者導入 Multi-Agent 開發流程
• 團隊建立 Workspace／Git 分工規範
• 企業導入 AI Coding Governance、SSDLC、安全治理
• 資深工程師處理 Agent Blocked、Troubleshooting

的完整操作手冊。

1.2 如何閱讀這份手冊

• 第一次接觸 Herdr：依序閱讀第 2～12 章（定位、核心概念、架構、安裝、Quick Start、操作方式）。
• 已經會用 Herdr，想導入 Multi-Agent 開發：直接跳到第 13～24 章（三大 Agent 實戰、Multi-Agent 模式、Web App／逆向工程／Framework Upgrade 案例、Git 策略）。
• 維運/資安/治理負責人：直接跳到第 31～50 章（維運 SOP、升級、備份、安全、企業治理、SSDLC、KPI、Rollout Plan）。
• 需要立即上手的資深同仁：直接看第 51 章 Cheat Sheet 與第 52 章 Prompt 範本。
• 決策者/架構師想快速判斷是否導入：直接看第 6 章比較表與第 55 章架構師最終評估。

1.3 與其他手冊的差異

本手冊聚焦在「Herdr 作為 Runtime／Workspace 層」，不重複說明 Claude Code、GitHub Copilot CLI、Codex、Spring Boot、Vue3 等工具本身的完整用法。若需要深入了解這些工具本身，請參閱本 Repository 既有的：

• Claude Code生態圈教學手冊
• Copilot CLI教學手冊
• OpenAI Codex生態系教學手冊
• Spring boot 4.x 教學手冊

1.4 本章 Checklist 與小結

• 已理解本手冊採用五層 Provenance 標示法
• 已理解本手冊聚焦於 Herdr 本身，Agent 工具細節請參閱既有手冊
• 已依自身角色（開發者／維運／治理／決策者）挑選適合的閱讀路徑

2. Herdr 簡介與定位

2.1 Herdr 是什麼

Herdr 官方將自己定位為「the runtime your coding agents live on」（官方已實作，README）——一個在背景常駐運行的 Server，把真實的終端機 Process（Shell、Claude Code、Codex、build 工具……）保存在其中，讓這些 Process 不因為 Client 斷線、筆電關機、SSH 中斷而消失（官方已實作，README：「Herdr is a background server; the terminals live inside it.」）。

官方文件對核心概念的定義是：「Herdr is a terminal workspace manager. It keeps real terminal processes running and adds structure around them.」（官方已實作，concepts 文件）。這句話點出兩個關鍵字：

1. Terminal Workspace Manager：管理真實終端機 Process 的存續與結構（Workspace／Tab／Pane）。
2. Adds structure around them：不只是「保存」，還在其上加了 Agent 偵測、狀態追蹤、Socket API 等「結構」。

2.2 Herdr 不只是這些

在第一次接觸 Herdr 時，很容易把它簡化理解成：

• ❌ 單純的 terminal（它是，但不只是）
• ❌ terminal multiplexer（它有這個能力，但不只是）
• ❌ tmux replacement（官方明確反對這種簡化理解，見第 6 章比較）
• ❌ AI CLI launcher（啟動 Agent 只是它其中一個能力）

正確的理解應該是：

Herdr 是專門讓 Coding Agent 長時間運作、管理多個 Agent、保存 Agent 執行環境、觀察 Agent 狀態、協調 Agent 工作，以及讓人類與 Agent 都能控制工作區的 Agent Runtime / Terminal Multiplexer / Workspace Management Layer。（此為本手冊之概念模型，非官方正式定義，標示為建議架構，用以幫助讀者建立心智模型）

官方也用一句話點出它與傳統 multiplexer 的本質差異：「tmux keeps terminals alive; so does Herdr. The difference is Herdr knows which terminals are agents, what state each one is in, and how to wait on them. tmux sees panes.」（官方已實作，herdr.dev/compare/）。

2.3 Herdr 在 AI Software Development Lifecycle 中的位置

flowchart TD
    Human["Human Developer / Architect"] --> Herdr["Herdr (Agent Runtime + Workspace Layer)"]
    Herdr --> Claude["Claude Code"]
    Herdr --> Codex["OpenAI Codex"]
    Herdr --> Copilot["GitHub Copilot CLI"]
    Claude --> Infra["Terminal / Process / Git / Build / Test"]
    Codex --> Infra
    Copilot --> Infra
    Infra --> Repo["Git Repository / CI / Artifact"]

Herdr 本身不寫程式、不做 code review、不執行 build，這些工作全部由 Agent 或既有工具鏈完成；Herdr 負責的是「讓這些工作可以長時間、多個並行、可被觀察與恢復地運作」。

2.4 Herdr 是否等於 Agent？是否取代 Claude Code / Codex / Copilot？

不是。 Herdr 本身不具備 LLM 推理能力，它不會幫你寫程式碼、不會回答需求問題。它是這些 Agent CLI 的「宿主環境」。拿掉 Herdr，Claude Code、Codex、Copilot CLI 依然可以在普通終端機裡執行；差別在於失去了：Session 持久化、跨裝置 Reconnect、多 Agent 狀態總覽、Socket API 自動化能力（官方已實作／建議架構混合，詳見第 4-5 章）。

2.5 Herdr 與 IDE、Agent Orchestrator 的關係

• 與 IDE 的關係：Herdr 不是 IDE，沒有程式碼編輯器、沒有語法高亮、沒有 Debugger。開發者仍然需要 VS Code / IntelliJ 等 IDE 來寫程式與除錯；Herdr 負責的是 IDE 之外，Agent 實際「動手做事」的終端機環境。兩者是互補關係，不是替代關係（建議架構）。
• 與 Agent Orchestrator 的關係：Herdr 提供 Agent 狀態可視化與 Socket API／CLI 可供腳本呼叫（官方已實作），但它不是一個完整的 Multi-Agent Orchestration Framework——它不內建任務分派佇列、不內建 Agent 間訊息傳遞協定、不內建重試/補償邏輯。若企業需要「Agent A 完成後自動觸發 Agent B」這類編排，仍需要在 Herdr 之上自行建立 Orchestration Layer（詳見第 27 章的界線分析）。

2.6 Herdr 的核心價值（企業視角）

2.7 AI Prompt 範例

角色：企業內部技術教育訓練講師
任務：用 3 分鐘的口語說明，向從未使用過 Herdr 的資深 Java 工程師解釋
「為什麼我們需要在終端機之上再加一層 Herdr，而不是直接開多個終端機視窗跑
Claude Code / Codex / Copilot CLI」。
限制：不要使用行銷語言，聚焦在「長時間運作」「多 Agent 狀態可視化」
「斷線恢復」三個具體痛點，並舉一個此工程師實際會遇到的情境。

2.8 本章 Checklist 與小結

• 能用一句話說明 Herdr 是什麼（Agent Runtime / Terminal Workspace Manager）
• 能說出 Herdr 不是 IDE、不是完整 Agent Orchestrator、不取代 Claude Code/Codex/Copilot CLI
• 理解 Herdr 在 AI SDLC 中的位置：承載 Agent 執行，而非取代 Agent 或既有工具鏈

3. 為什麼企業需要 Herdr

3.1 傳統 AI Coding Workflow 的真實痛點

在還沒有 Runtime 層的情況下，一位工程師若要同時運用多個 AI Coding Agent，典型的作法如下：

Terminal 1 → Claude Code（負責後端邏輯）
Terminal 2 → Codex（負責前端元件）
Terminal 3 → GitHub Copilot CLI（負責測試）
Terminal 4 → npm / Maven（build）
Terminal 5 → 手動執行測試
Terminal 6 → git status / git diff

這個模式在小型任務尚可運作，但隨著任務規模與 Agent 數量增加，會逐一浮現以下問題：

3.2 Herdr 如何改善

flowchart LR
    subgraph Before["導入前"]
        T1["Terminal 1-6<br/>(各自獨立、易失聯)"]
    end
    subgraph After["導入 Herdr 後"]
        Server["Herdr Server<br/>(常駐、狀態集中)"]
        W["Workspace<br/>(結構化組織)"]
        Server --> W
    end
    Before -. "重構" .-> After

• 長時間運作：Agent Process 由 Herdr Server 保存，Client 斷線不影響 Process 存續（官方已實作）。
• 狀態集中可視化：在同一個 Client UI 中看到所有 Pane 的 Agent 狀態（working/idle/blocked/done/unknown）（官方已實作）。
• 結構化工作區：用 Workspace／Tab／Pane 階層取代散亂的視窗（官方已實作）。
• 隨處恢復：從任何裝置 herdr 重新連上同一個 Session（官方已實作）。
• 自動化銜接：CLI／Socket API 讓維運腳本、CI 前置檢查等可以查詢 Agent 狀態（官方已實作）。

3.3 Scenario：一位資深工程師的一天

一位負責 Legacy Java 系統升級的工程師，早上在公司啟動 Herdr Session，開了三個 Workspace 分別對應「後端升級」「前端重構」「測試補強」，各自啟動 Claude Code。中午開會前 prefix+q detach，闔上筆電去開會。下午回來，在會議室用平板透過瀏覽器 SSH 或另一台筆電重新 herdr attach，三個 Agent 仍在原本的狀態繼續運作，其中一個因為等待資料庫連線字串確認而顯示 blocked，工程師立刻補上資訊讓它繼續。這個情境是 Herdr 的核心設計目標所直接對應的（建議架構，依官方能力推導之典型使用情境）。

3.4 本章 Checklist 與小結

• 能列舉至少 5 項「多終端機管理 AI Agent」的痛點
• 能說明 Herdr Server／Client 分離架構如何解決「斷線即中斷」問題
• 理解 Herdr 帶來的價值主要是「Runtime 持久化」與「狀態可視化」，而非取代 Agent 本身能力

4. Herdr 核心概念

4.1 六大核心概念

Herdr 官方文件（concepts 文件）定義了以下核心概念，彼此構成一個階層關係（官方已實作）：

再加上疊加在 Pane 之上的：

• Agent：當一個 Pane 裡執行的是被 Herdr 辨識出的 Coding Agent（如 Claude Code）時，Herdr 會為這個 Pane 附加 Agent 身分與狀態追蹤（官方已實作）。

4.2 概念階層圖

flowchart TD
    Session["Session<br/>(持久化 Server 命名空間)"] --> Server["Server"]
    Server --> Client1["Client (筆電)"]
    Server --> Client2["Client (公司桌機)"]
    Server --> Workspace1["Workspace: bank-web-platform"]
    Server --> Workspace2["Workspace: legacy-migration"]
    Workspace1 --> Tab1["Tab: backend"]
    Workspace1 --> Tab2["Tab: frontend"]
    Tab1 --> Pane1["Pane 1"]
    Tab1 --> Pane2["Pane 2"]
    Pane1 --> Agent1["Agent: Claude Code (working)"]
    Pane2 --> Agent2["Agent: Codex (idle)"]

這張圖對應官方 ID 規則：Workspace 用 w1 表示，其下 Tab 用 w1:t1，其下 Pane 用 w1:p1（Source-confirmed，CLI/Skill 文件）。

4.3 ID 命名規則實例

w1          → Workspace 1
w1:t1       → Workspace 1 底下的 Tab 1
w1:p1       → Workspace 1 底下的 Pane 1

這套扁平化 ID 規則，是 Herdr CLI 與 Socket API 用來精準定址單一 Pane／Tab／Workspace 的方式（Source-confirmed），例如：

# 示意：查詢特定 Pane 的 Agent 狀態
herdr agent get w1:p1

4.4 Server／Client 分離的意義

Herdr 採用 Client/Server 架構：Server 是背景 Process，負責保存所有 Pane 的實際終端機狀態；Client 是你連上去看畫面、送鍵盤/滑鼠事件的 UI（官方已實作）。這個分離帶來的直接效果：

• 關閉 Client（甚至整台裝置斷線）不影響 Server 上運作中的 Process。
• 同一個 Server 可以先後被不同 Client（不同裝置、不同時間）attach。
• herdr server stop 才會真正終止所有 Process；單純關閉視窗只是 Client detach（官方已實作，concepts 文件）。

4.5 Scenario：一個中型 Web 專案的 Workspace 規劃

Workspace: bank-web-platform
├── Tab: architecture   → Pane: Claude Code（架構規劃）
├── Tab: backend        → Pane: Claude Code（Spring Boot 開發）
├── Tab: frontend       → Pane: Codex（Vue3 開發）
├── Tab: test           → Pane: Copilot CLI（測試撰寫）
└── Tab: review         → Pane: 人類 Shell（git diff / code review）

（建議架構，第 13 章起會提供更完整的企業級 Workspace 設計規範）

4.6 AI Prompt 範例

角色：Herdr 平台導入顧問
任務：針對「Legacy Java 逆向工程」專案，設計一組 Workspace/Tab/Pane 命名規劃，
需求：
- 一個 Workspace 對應此專案
- 至少包含 architecture、reverse-engineering、documentation、test 四個 Tab
- 每個 Tab 說明應該指派哪一種 Agent（Claude Code / Codex / Copilot CLI / 人類）
輸出格式：樹狀文字圖 + 一句話說明每個 Tab 的職責

4.7 本章 Checklist 與小結

• 能畫出 Session → Server/Client → Workspace → Tab → Pane → Agent 的階層圖
• 理解 w1:t1:p1 這類 ID 命名規則的用途
• 理解 Client 關閉 ≠ Server 停止；只有 herdr server stop 才真正終止 Process

5. Herdr 系統架構

5.1 架構總覽

flowchart TD
    Human["Human"] --> Client["Herdr Client (TUI)"]
    Client -->|"Socket API"| Server["Herdr Server / Session"]
    Server --> WM["Workspace Manager"]
    Server --> TM["Tab Manager"]
    Server --> PM["Pane Manager"]
    Server --> TR["Terminal Runtime<br/>(PTY on Unix / ConPTY on Windows)"]
    Server --> AD["Agent Detection<br/>(Screen Manifest / Lifecycle Hooks)"]
    Server --> AS["Agent State Tracking"]
    Server --> Sock["Socket API"]
    Sock --> CLI["herdr CLI"]
    Server --> Plugin["Plugin System"]
    TR --> Agents["Coding Agents<br/>(Claude Code / Codex / Copilot CLI / ...)"]

（建議架構：此圖為本手冊依官方文件描述之元件重新繪製之整合視圖，元件邊界依官方 docs 站 Install/Concepts/Agents/Socket API/Plugins 頁面之敘述整理，非官方原始碼模組圖）

5.2 Process Lifecycle

一個 Agent 從啟動到結束，在 Herdr 中的生命週期大致如下（建議架構，依官方 Agent 狀態機推導）：

stateDiagram-v2
    [*] --> idle
    idle --> working: Agent 開始處理任務
    working --> blocked: 需要人類確認/輸入
    blocked --> working: 人類回應後恢復
    working --> done: 任務完成
    working --> idle: 任務間的等待
    done --> [*]
    working --> unknown: 偵測機制無法判斷
    idle --> unknown: 偵測機制無法判斷

官方明確定義的狀態為 working／idle／blocked／done／unknown（官方已實作，agents 文件），狀態轉換的判斷依據見第 5.4 節與第 22 章。

5.3 Session Persistence 與 Terminal Persistence

• Session Persistence：Herdr Server 作為背景 Process 常駐，Session 資訊（Workspace/Tab/Pane 結構）在 Server 存活期間持續存在（官方已實作）。
• Terminal Persistence：每個 Pane 底層是一個真實 PTY（Unix）或 ConPTY（Windows）Process，只要 Server 不停止，這個 Process 的 stdout/stderr 緩衝與存活狀態就會被保留，Client 重新 attach 時可以看到之前的輸出（官方已實作）。
• 這兩者合稱為「Herdr session persistence」，但這不等於程式碼被保存或備份——它只保存「終端機 Process 的執行狀態」，不是 Git 意義上的版本控制備份（見第 33 章的重要區分：Session Recovery ≠ Code Recovery）。

官方 session-state 文件將「保存了什麼」拆成四種明確不同的情境，企業規劃維運 SOP（第 31-33 章）前應先理解這張矩陣，避免對「重啟後還在不在」有錯誤期待（官方已實作）：

其中兩個常被誤解的細節：

1. pane_history（近期畫面內容回放）預設關閉，因為終端輸出可能含機密、Token、指令內容，官方刻意不預設保存；企業若要啟用，需在 config.toml 明確設定 [experimental] pane_history = true，且應把這份紀錄視為與終端機歷史紀錄同等機敏（官方已實作，session-state 文件）。
2. Native Session Restore（Agent 對話接續）需要對應 Agent 已安裝「當前版本」的官方整合（見第 29.3 節版本需求表），版本過舊、未安裝、或 Session 參照失效時，Herdr 只能把該 Pane 恢復成一個位於原工作目錄的全新 Shell，Agent 之前的對話上下文並不會自動回來。

Live Handoff 是專門為「更新／--remote 需要替換正在運作中的 Server」所設計的特殊路徑：它嘗試把存活的 Pane 直接轉移給新 Server，而不是等舊 Server 停止後再從快照重建，因此可以保留 PTY Process 本身不中斷；但它是實驗性、需明確加旗標啟用的功能（herdr update --handoff／herdr --remote <host> --handoff），且僅適用於 Herdr 自身更新器管理的安裝方式——透過 Homebrew／mise／Nix 安裝時，herdr update 本身會被停用，也就無法使用 Handoff（官方已實作，session-state 文件，另見第 32.4 節）。

5.4 Detach / Attach

• Detach：預設鍵位 prefix+q（即 ctrl+b 後按 q），Client 中斷連線，Server 與其下所有 Pane 繼續運作（官方已實作，keyboard 文件）。
• Attach：重新執行 herdr（或 herdr --session <name>）即可重新連上原本的 Server，畫面恢復到 detach 前的狀態（官方已實作）。
• 完全停止：herdr server stop 才會終止 Server 與其下所有 Process（官方已實作）。

5.5 Agent Detection：兩層機制

Herdr 用兩層機制判斷一個 Pane 裡是不是在跑 Agent、目前狀態為何（官方已實作，agents 文件）：

1. Lifecycle Hooks／Plugin Integration（權威來源）：少數 Agent（Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、MastraCode）安裝對應整合後，會主動回報自己的狀態，Herdr 直接信任這個回報，不需要用畫面猜測。
2. Screen Manifest（預設 fallback）：針對其餘 Agent（含 Claude Code、Codex、GitHub Copilot CLI、Cursor Agent CLI 等），Herdr 用 TOML 規則描述的「畫面特徵」（終端標題、OSC progress 序列、畫面下緣文字模式）去比對終端機的即時畫面快照（bottom-buffer screen snapshot），據此推論狀態；只有畫面特徵明確符合「等待核准/提問/權限」樣式時才會標記為 blocked，否則預設為 idle（官方已實作）。

重要澄清：Screen Manifest 偵測是「畫面樣式比對」，不是 Herdr 真正理解 Agent 在想什麼、做什麼（不可誤寫為「Agent 語意理解」）。這是本手冊第 55 章「架構師最終評估」特別強調要避免的過度宣稱之一。

細緻區分：Integration 實際提供的兩種能力，官方文件（integrations 文件）明確拆成兩個獨立軸線，不應混為一談：

換句話說，安裝了 Claude Code／Codex／Copilot CLI 的官方 Integration，並不會讓狀態判斷變成 Lifecycle Hook 權威——這三者的狀態來源仍是 Screen Manifest，Integration 只是讓 Server 重啟後能自動 claude --resume <id> 之類的方式復原對話（Source-confirmed，session-state／integrations 文件，第 29 章有更完整的整合深度比較）。

5.6 Client/Server 分離、Local 與 Remote 執行

5.7 Scenario：架構師評估導入風險

一位 Software Architect 在評估是否導入 Herdr 時，最關心的問題通常是：「Server 掛掉會怎樣？」「多個人能不能共用同一個 Server？」——目前官方文件描述的模型是單一 Server 對應單一使用者的 Session，Client/Server 分離主要解決的是「同一個人跨裝置/跨時間」的持久化問題，而不是「多人協作編輯同一個 Session」的多使用者共享模型（Source-confirmed，官方文件未描述多使用者共享 Session 的正式支援；企業若有此需求，需自行評估或詢問官方，勿假設存在）。

5.8 AI Prompt 範例

角色：DevSecOps Architect
任務：畫出一張「Herdr Server 在公司 Dev VM 上運行、多位工程師各自 SSH 進來
啟動自己的 Herdr Session」的架構圖，並標註：
1. 每位工程師的 Session 是否互相隔離
2. Server Process 的權限（跑在哪個 OS 使用者底下）
3. 一旦 Dev VM 重啟，所有 Session 會發生什麼事
輸出：Mermaid flowchart + 3 條風險備註

5.9 本章 Checklist 與小結

• 理解 Session Persistence／Terminal Persistence 的意義與限制
• 能說明 Agent Detection 的兩層機制（Lifecycle Hooks vs Screen Manifest）
• 理解 Session Recovery 不等於 Code Backup
• 理解目前官方模型偏向單使用者跨裝置持久化，而非多使用者共享同一 Session

6. Herdr 與 tmux／zellij／IDE／Agent Orchestrator 比較

6.1 完整比較表

6.2 為什麼不應該只把 Herdr 當成 tmux replacement

官方自己給出的區分最精準：「tmux keeps terminals alive; so does Herdr. The difference is Herdr knows which terminals are agents, what state each one is in, and how to wait on them. tmux sees panes.」（官方已實作，herdr.dev/compare/）。

與 zellij 比較，官方的說法是：「Zellij is a friendlier workspace for humans in terminals. Herdr is a runtime for agents in terminals: state, waits, direct attach, and an API.」（官方已實作，同上）。

換句話說：

tmux／zellij 解決「終端機本身的多工與持久化」；Herdr 在此基礎之上，再解決「終端機裡面跑的是不是一個 Agent、這個 Agent 現在是什麼狀態、我可不可以用程式化方式等待它完成」這一層問題（建議架構，本手冊對官方比較頁面的延伸詮釋）。

官方比較頁面（herdr.dev/compare/）實際涵蓋的比較對象不只 tmux／zellij，還包含終端機應用（cmux、Warp）、Process Dashboard（Solo）、以及以 Git Worktree／Diff 為核心的 Agent 管理應用（Conductor、Emdash、Superset）與 opencode 內建的 web UI（官方已實作）。官方對這些工具的核心區分邏輯一致：「Herdr 是 Runtime（Server 端持有終端機），其餘多數是 App（UI 關閉即中斷）」——例如 cmux／Warp 屬於取代既有終端機環境的應用，Herdr 則在既有終端機（iTerm、Windows Terminal、SSH 連線等）內運作，不要求換掉終端機本身；Conductor／Emdash／Superset 這類「Agent 管理 App」雖然也處理 Worktree 與 Diff 檢視，但關閉 App 通常會讓底層 Agent Process 一併停止，Herdr 的 Agent 則因為活在 Server 內而不受 Client 關閉影響（官方已實作，herdr.dev/compare/）。企業選型時若把 Herdr 單純與 tmux 比較，容易低估它與這類「Agent 管理 App」之間的重疊與差異，選型會議應一併納入評估（建議架構）。

6.3 Herdr 與 Agent Orchestrator 的界線

Herdr 提供「觀察」與「等待」的原語（例如 herdr agent wait w1:p1 --until done，官方已實作，socket-api 文件），但它不是一個具備任務佇列、DAG 編排、重試補償語意的 Orchestration Framework。若企業需要「Agent A 完成 → 自動觸發 Agent B → 失敗自動重試」這樣的完整編排邏輯，仍需要在 Herdr 之上另行建立 Orchestration Layer（此點會在第 27 章深入討論）。

6.4 Scenario：架構師選型會議

在一場工具選型會議上，若有人提出「我們現有的 tmux + shell script 已經很夠用，為什麼要導入 Herdr？」，比較表中最值得強調的差異點是：tmux 不知道 Pane 裡面在跑什麼、更不知道它是否卡住；而多 Agent 並行時，「哪個 Agent 卡住了」正是實務上最容易被忽略、卻最影響交付時程的問題。

6.5 本章 Checklist 與小結

• 能用官方原文（tmux sees panes vs Herdr knows agent state）向同仁解釋差異
• 理解 Herdr 不具備完整任務編排能力，不能取代 Orchestration Layer
• 能填寫本比較表向團隊/主管簡報選型理由

7. 安裝環境：Linux／macOS

7.1 系統需求

官方安裝腳本以 Linux 與 macOS 為 Stable Channel 的第一級支援平台（官方已實作）。Herdr 是單一 Rust 執行檔，不需要額外的 Runtime（如 JVM／Node.js）即可運作（官方已實作，README）。

7.2 安裝方式

# Linux / macOS — 官方安裝腳本（Stable Channel）
curl -fsSL https://herdr.dev/install.sh | sh

其他官方支援的安裝管道（官方已實作，agent-guide 文件）：

# Homebrew（macOS／Linuxbrew）
brew install herdr

# mise（跨平台版本管理工具）
mise use -g herdr

# Nix
nix run github:herdrdev/herdr
nix profile install github:herdrdev/herdr/v0.8.0

注意：本手冊不建議使用 cargo install 作為終端使用者安裝方式——cargo 建置流程在官方 README 中屬於「從原始碼建置」的開發者/貢獻者流程，並非官方推薦給一般使用者的發布管道（Source-confirmed，不可視為官方正式安裝方式）。

7.3 PATH 設定

安裝腳本通常會將 herdr 執行檔放入使用者可執行路徑（例如 ~/.local/bin 或 Homebrew 的標準路徑）。若安裝後 herdr 指令找不到，請確認該路徑是否已加入 $PATH（Source-confirmed，依安裝方式而異，具體路徑請以安裝腳本輸出訊息為準）。

7.4 驗證安裝

herdr --version

7.5 啟動

# 在專案目錄下執行，未指定 Session 時會自動開啟一個 Workspace
herdr

7.6 本章 Checklist 與小結

• herdr --version 可正確輸出版本號
• 已確認 herdr 執行檔所在路徑已加入 $PATH
• 已確認使用的安裝管道（install.sh／Homebrew／mise／Nix）以利日後升級時採用對應方式（見第 32 章）

8. 安裝環境：Windows

8.1 Windows 支援現況：正式支援（GA）

本節於 2026-09-06 複查時全面改寫。 Herdr 的原生 Windows 版本已於 v0.8.2（2026-08-19）轉為正式支援（General Availability），官方 Windows 文件的措辭是「Native Windows support is generally available」（官方已實作，Windows 文件）。這帶來三項對企業導入直接相關的改變：

• Stable 成為 Windows 的預設更新通道。過去「Windows 只能待在 Preview、herdr channel set stable 會被拒絕」的限制已不存在；Windows 現在與 Linux/macOS 一樣可用 herdr channel set stable / herdr channel set preview 雙向切換（官方已實作，Install／Windows 文件）。
• 既有的 Preview 安裝不會自動轉為 Stable。官方明確說明，在 GA 之前就裝好、且停留在 Preview 通道的安裝會維持在 Preview，必須手動執行 herdr channel set stable 才會切回穩定通道（官方已實作）。企業若在 2026-08-19 之前已於 Windows 機器上部署 Herdr，升級 SOP（第 32 章）應額外加入這一步的稽核。
• 終端模型仍是 ConPTY，而非 Unix PTY（官方已實作）。Herdr 在 Windows 上內建捆綁一份 Microsoft ConPTY runtime，原因是較舊的 Windows 10 build 會吞掉 Kitty keyboard protocol 的按鍵序列；若企業環境有政策或相容性考量需要改用系統內建的 ConPTY，可設定環境變數 HERDR_WINDOWS_CONPTY=system 退回（官方已實作，Windows 文件）。

企業使用建議（建議架構）：GA 不等於「功能與 Linux/macOS 對等」。官方在宣告 GA 的同時，仍以獨立段落列出一批原生 Windows 不支援或僅部分支援的功能（見第 8.3 節）。因此正確的導入判準已經不是「Preview 穩不穩」，而是「我的工作流程有沒有用到那批缺口功能」——這正是第 8.4 節決策矩陣要回答的問題。

與本手冊舊版的差異提醒：初版（2026-08-12 基準）曾引述官方對 Windows 未來定位的三種可能結局（轉為 Stable／持續停留 Preview／縮減範圍），並據此建議企業不要把「即將轉正」當作規劃前提。該段落已因 v0.8.2 的 GA 而失效並移除——官方選擇的是第一種結局。舊版讀者若曾以「Windows 不會轉正」為前提做過架構決策，建議依本章重新評估。

8.2 安裝方式（Windows）

# Windows — 官方安裝腳本（GA 後預設即為 Stable Channel）
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

部分企業的端點防護（EDR／AppLocker／防毒軟體）會攔截 irm ... | iex 這種「下載後直接執行」的模式。官方為此提供了一組改走實體檔案的備援指令（官方已實作，Install 文件）：

# 端點防護阻擋上述指令時的官方備援方式
curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd

驗證安裝：

herdr --version

# GA 後，全新安裝應顯示 stable；
# 若這裡顯示 preview，代表這是 GA 之前留下的舊安裝，需手動切換（見第 8.1 節）
herdr channel show
herdr channel set stable

8.3 已知限制

GA 之後，Windows 的限制清單從「整個平台都是 Preview」收斂為「特定功能明確不支援 / 部分支援」。以下依官方 Windows 文件現況分成三類，企業評估時請直接對照自己的使用情境（官方已實作，Windows 文件）：

（一）明確不支援

（二）部分支援

（三）已知行為差異

• 原生游標在輸出頻繁時可能閃爍、跳動或顯示過期位置，因此 Herdr 在 Windows 上預設採用自繪游標（drawn cursor）（官方已實作）。
• 但自繪游標模式無法正確錨定中／日／韓 IME 的輸入視窗——這是一組互相衝突的取捨。若團隊大量使用中文輸入法，需調整 host_cursor 設定並實測，官方 Troubleshooting 頁面對此有專節（見第 44 章）。
• 鍵盤／滑鼠回報行為取決於終端機；ctrl+j 在 Windows Terminal 與 Alacritty 中會被保留（官方已實作）。

相較舊版已移除的兩列：「發布通道僅 Preview、無法切換 Stable」與「Plugin 支援標示為 Preview」在 v0.8.2 之後均已不成立，本表不再列出。

8.4 Windows 原生 vs WSL2 Linux 的分析建議

Windows
 ├── WSL2
 │    └── Linux（Stable Channel）
 │         └── Herdr
 │              ├── Claude Code
 │              ├── Codex
 │              └── Copilot CLI
 │
 └── VS Code / IntelliJ（連接 WSL2 或直接操作 Windows 端）

GA 之後，兩條路線都站在 Stable 通道上，因此比較的基準已從「哪一邊比較穩」轉為「哪一邊具備我需要的功能」。以下為中性並列的決策矩陣（官方已實作項目依 Windows 文件；評估欄位為建議架構）：

決策準則（建議架構，非官方立場）——不再有單一推薦答案，請依下列判準擇一：

• 選 WSL2 內的 Linux Herdr，若你的流程符合任一項：需要 Direct Terminal Attach（例如資安唯讀稽核牆，第 25.5 節）／需要 Live Handoff 做無中斷升級（第 32.4 節）／規劃「集中式 Dev Server 供多人 --remote 連入」的架構（第 25.4、25.6 節）／團隊重度使用中文輸入法與 Agent 對話／主要工具鏈是 Linux 導向（Maven、Shell 腳本、容器化建置）。
• 選原生 Windows Herdr，若你的流程符合：主要開發標的是 .NET／Windows 專屬 SDK，跨進 WSL2 反而增加路徑與權限複雜度／團隊只需要「本機開多個 Agent Pane、斷線後可重新 attach」的核心價值，用不到上述缺口功能／希望降低導入摩擦（不需要求每位同仁先裝設定 WSL2）。
• 兩者皆可時，建議以「團隊既有工具鏈的重心」作為 tie-breaker，而不是以平台成熟度——因為在 GA 之後，這兩者的成熟度差距已不再是決策主軸。

8.5 Scenario：企業 Windows 開發機導入評估

一個以 Windows 為標準配發機種的企業團隊，在導入 Herdr 前應該問的問題，已經不再是「能不能接受在 WSL2 裡運作」，而是：「我們規劃的 Herdr 使用方式，有沒有踩到第 8.3 節那七項不支援的功能？」

實務上的判讀方式是把團隊的預期用法逐條對照：如果只是「每人在自己的 Windows 筆電上開 3～5 個 Pane 跑 Claude Code／Codex／Copilot CLI，晚上關掉 Client、隔天重新 attach」，那麼七項缺口一項都不會踩到，原生 Windows 已是完全合理的正式選項，不需要為此要求全團隊導入 WSL2。反過來，如果架構藍圖裡出現「集中式 Dev Server」「資安唯讀監看牆」「升級不可中斷」任何一項，那就必須走 Linux（WSL2 或獨立的 Linux/macOS 主機），因為那三項在原生 Windows 上是功能缺口，不是穩定度問題，不會靠多測試幾輪解決。

8.6 本章 Checklist 與小結

• 已知悉 Windows 自 v0.8.2 起為正式支援（GA），Stable 為預設通道，本手冊舊版的 Preview 描述已失效
• 若為 GA 前既有安裝，已執行 herdr channel show 確認通道，必要時以 herdr channel set stable 手動切換
• 已逐條對照第 8.3 節的「明確不支援」七項，確認團隊規劃的用法是否踩到
• 已依 8.4 節決策準則（而非平台成熟度）選定原生 Windows 或 WSL2 路線，並記錄選擇理由
• 若團隊重度使用中文輸入法，已實測 CJK IME 與游標繪製模式的取捨（見第 44 章）

8.7 v0.8.2 的 Windows 相關新增能力

除了 GA 本身，v0.8.2 還針對 Windows 補上了數項具體能力，這些是評估「原生 Windows 是否足夠」時應一併納入的正面因素（官方已實作，v0.8.2 Release Notes）：

建議架構：對絕大多數以 Windows 為標準配發機種的企業，本手冊認為 v0.8.2 之後最務實的架構是「Windows 原生 Herdr 作為 --remote Client + Linux Dev VM 作為 Server」——它同時取得 Windows 端的原生使用體驗與 Linux 端的完整功能（Direct Attach、Live Handoff、集中管理），且完全落在官方支援範圍內，不需要每位同仁自行維護 WSL2 環境。

9. 安裝驗證與 Installation Checklist

9.1 驗證指令

# 確認可執行、版本資訊
herdr --version

# 查看內建說明（子指令與旗標）
herdr --help

# 查看目前 Server/Client 狀態
herdr status

以上指令為官方文件與 CLI 說明中可查證之指令（官方已實作／Source-confirmed）。其餘子指令請以 herdr <group> 不帶參數列出可用選項（例如 herdr workspace、herdr agent），不要自行假設不存在的旗標。

9.2 常見安裝後檢查項目

1. herdr --version 能正確輸出版本
2. herdr 能在專案目錄下成功啟動並開啟一個 Workspace
3. 終端機視窗大小調整後，Herdr UI 能正確重繪
4. 滑鼠點擊 Pane／Tab 能正確切換焦點（官方已實作，滑鼠優先設計）
5. prefix+q 能正確 detach，重新執行 herdr 能重新 attach
6. herdr server stop 能正確終止 Server 與其下 Process

9.3 Installation Checklist

• herdr --version 顯示的版本與官方 Release 頁面一致
• 確認安裝管道（install.sh／Homebrew／mise／Nix／Windows Preview），並記錄於團隊內部 Wiki 以利日後升級對照（見第 32 章）
• 已完成一次 Detach → Attach 驗證
• 已完成一次 herdr server stop 驗證，確認 Process 確實被終止
• （Windows）已確認目前為 Preview Channel，並記錄於團隊已知限制清單

9.4 常見錯誤（安裝階段）

（完整常見錯誤清單見第 43 章，本節僅列安裝階段常見情境）

10. Herdr Quick Start

10.1 十步驟從零開始

官方 Quick Start 文件描述的核心流程為：於專案目錄執行 herdr、以滑鼠操作、在 Pane 內啟動 Agent、視需要進入 Prefix Mode 使用鍵盤、Detach、以 herdr server stop 完全停止（官方已實作，quick-start 文件）。本節將其擴展為十個實作步驟：

Step 1：安裝 Herdr

curl -fsSL https://herdr.dev/install.sh | sh   # Linux/macOS

預期結果：herdr --version 有輸出。常見錯誤：PATH 未設定（見第 9.4 節）。

Step 2：啟動 Herdr

cd ~/projects/bank-web-platform
herdr

UI 操作：Herdr 會自動開啟一個 Workspace（若尚未存在）。預期結果：看到 Herdr TUI 畫面，含至少一個 Pane。

Step 3：建立 Workspace

# 示意：以 CLI 建立具名 Workspace（實際操作亦可透過滑鼠於 UI 新增）
herdr workspace create bank-web-platform

預期結果：新的 Workspace 出現在 Workspace 清單中。

Step 4：建立 Pane

UI 操作：滑鼠右鍵於現有 Pane 選擇分割，或使用鍵盤 prefix+v（右分割）／prefix+minus（下分割）。預期結果：畫面出現新的終端機格子。

Step 5：啟動 Claude Code

# 在其中一個 Pane 內
claude

預期結果：Claude Code 啟動，Herdr 開始針對此 Pane 進行 Agent 偵測，狀態顯示為 idle 或 working。

Step 6：啟動 Codex

# 在另一個 Pane 內
codex

Step 7：啟動 GitHub Copilot CLI

# 在第三個 Pane 內（實際指令名稱依 Copilot CLI 官方安裝方式而定）
copilot

Step 8：觀察 Agent 狀態

UI 操作：在 Herdr Client 畫面中，各 Pane 標題或狀態標示會顯示 working／idle／blocked／done／unknown（官方已實作）。預期結果：可以一眼看出哪個 Agent 正在工作、哪個卡住。常見錯誤：剛啟動 Agent 的前幾秒可能顯示 unknown，屬正常現象，待畫面特徵穩定後會轉為正確狀態。

Step 9：Detach

鍵盤操作：ctrl+b 進入 Prefix Mode，再按 q。預期結果：Client 離線，終端機提示字元恢復正常，Server 持續在背景運作。

Step 10：Reconnect

herdr
# 或指定 Session
herdr --session <name>

預期結果：畫面恢復到 detach 前的狀態，所有 Pane 與 Agent 狀態都還在。

10.2 Troubleshooting（Quick Start 階段）

10.3 本章 Checklist 與小結

• 完成一次完整的「安裝 → 啟動 → 建立 Workspace/Pane → 啟動 Agent → Detach → Attach」流程
• 能正確辨識 Agent 狀態顯示（working/idle/blocked/done/unknown）
• 理解 unknown 狀態不代表錯誤，而是偵測機制尚無法判斷

11. Keyboard／Mouse 操作

11.1 三種操作模式

Herdr 定義三種互動模式（官方已實作，concepts／keyboard 文件）：

11.2 常用鍵盤操作（預設鍵位）

（以上鍵位為官方文件所載之預設值，官方已實作；企業可依團隊習慣於 config.toml 的 [keys] 區塊重新綁定，見第 30 章）

11.3 Copy Mode 內操作

進入 Copy Mode（prefix+[）後（官方已實作，keyboard 文件）：

w/b/e 與 W/B/E 的差異：小寫版本會在標點符號處停下（例如 PaymentController.findById(id) 會被拆成多段），大寫的 big-word 版本只以空白分隔，整串會被視為一個單位。實務上從 Agent 輸出中複製一整個檔案路徑、完整類別名稱或一段指令時，大寫版本效率明顯較高（建議架構）。

11.4 滑鼠操作

Herdr 採「滑鼠優先」設計（官方已實作，README／首頁敘述），常見滑鼠操作包含：

• 點擊 Pane／Tab／Workspace 直接切換焦點
• 拖曳調整 Pane 大小
• 拖曳分割/合併版面
• 右鍵開啟選單（例如快速分割 Pane）

11.5 Scenario：鍵盤 vs 滑鼠的團隊規範

對於習慣 tmux 鍵盤流的資深工程師，建議保留 Prefix Key 操作以維持肌肉記憶；對於較少使用終端機 multiplexer 的前端/QA 同仁，建議直接以滑鼠操作 Pane/Tab，降低學習門檻（建議架構）。

11.6 本章 Checklist 與小結

• 能分辨 Terminal Mode／Prefix Mode／Navigate Mode 的差異
• 熟悉至少 8 個常用鍵位（split／navigate／detach／zoom／copy mode）
• 知道滑鼠可以完成大部分基本操作，鍵盤非必要但能提升效率
• 已知悉 Copy Mode 的 big-word motions（W／B／E）可加速複製長路徑與類別名稱

11.7 v0.8.2 鍵盤／滑鼠新增能力

v0.8.2 針對操作效率新增了數項與本章直接相關的能力，既有團隊鍵位規範（第 11.5 節）可據此檢討是否調整（官方已實作，v0.8.2 Release Notes／keyboard 文件）：

鍵位還原指令（Source-confirmed）：

# 將鍵盤綁定還原為官方 v2 預設鍵位
herdr config reset-keys

此指令見於官方 configuration 文件，但該頁面未逐一列出「v2 預設鍵位」與舊版鍵位的完整差異對照。企業若曾大量自訂 [keys] 區塊，執行前務必先備份 config.toml（見第 33 章），並於執行後以 prefix+? 叫出即時說明畫面確認實際鍵位，不要假設與本手冊第 11.2 節的表格完全一致。

企業應用建議（建議架構）：Tab 重新排序與直接調整 Pane 大小這兩組鍵位屬於「可選綁定」，預設可能未啟用。若團隊採用第 12 章的 Workspace 分層規範、且經常需要在多個 Agent Pane 之間切換注意力，建議在團隊共用的 config.toml 範本中統一啟用並固定鍵位，避免每位成員自訂造成互相支援時的操作落差。

12. Workspace 設計（企業級規範）

12.1 企業級 Workspace 命名與分層原則（建議架構）

本節全部內容為本手冊依 Herdr 官方 Workspace/Tab/Pane 概念（見第 4 章）延伸之企業導入建議，標示為建議架構，非官方規範。

原則一：一個 Project 對應一個 Workspace。 避免把多個不相關專案塞進同一個 Workspace，導致 Tab 爆炸、難以辨識歸屬。

原則二：一個 Agent 對應一個 Pane。 避免多個 Agent 共用同一個 Pane（會互相干擾終端機輸出、Agent 偵測也會錯亂）。

原則三：一個任務對應一個 Tab（視情境彈性調整）。 對於中大型任務，用 Tab 區分「架構」「後端」「前端」「測試」「安全」等不同工作面向。

原則四：多個 Agent 可以共用一個 Workspace，但不建議共用同一份 working directory 寫入同一批檔案（見第 23 章 Git 策略）。

12.2 範例一：企業 Web Application Workspace

bank-platform
├── frontend
├── backend
├── database
├── test
├── devops
├── security
├── claude       (Claude Code 專用 Pane/Tab)
├── codex        (Codex 專用 Pane/Tab)
└── copilot      (Copilot CLI 專用 Pane/Tab)

12.3 範例二：以角色分層的 Workspace

Project Workspace
 ├── Architecture
 ├── Frontend
 ├── Backend
 ├── Database
 ├── Test
 ├── Security
 └── AI Agents

12.4 何時該用哪種模式

12.5 Scenario：從單人開發擴展到團隊協作

一位工程師一開始只用單一 Workspace 處理個人任務；隨著專案擴大到需要前後端與測試同步進行，逐步拆分成多個 Tab；當專案進一步擴大為跨團隊（後端團隊、前端團隊、資安團隊各自維運自己的 Agent 工作），則建議切分成多個 Workspace，並搭配第 23-24 章的 Git Worktree 策略，避免多人多 Agent 互相覆蓋彼此的工作目錄。

12.6 AI Prompt 範例

角色：Herdr Workspace 規劃顧問
任務：為一個「將 Legacy COBOL 訂單系統重構為 Java 25 + Spring Boot 4.x 微服務」
的專案，設計 Workspace/Tab/Pane 配置。
限制：
- 需要同時進行逆向工程分析、架構設計、程式碼實作、測試撰寫、安全掃描
- 需標註每個 Tab 建議指派的 Agent（Claude Code/Codex/Copilot CLI/人類）
- 需標註哪些 Tab 之間有交付依賴關係（例如逆向工程需先於架構設計完成）
輸出：樹狀圖 + 依賴關係說明

12.7 本章 Checklist 與小結

• 已建立團隊內部 Workspace 命名規範文件
• 已確認「一個 Agent 一個 Pane」原則被遵守
• 已規劃好何時該用多 Workspace vs 單 Workspace 多 Tab

13. Claude Code + Herdr 實戰

13.1 啟動與基本操作

Claude Code 是 Herdr 官方明確列於支援清單中的 Agent（官方已實作，agents 文件），偵測方式為 Screen Manifest（見第 5.5、29 章）。在一個 Pane 內啟動：

claude

13.2 如何保持 Session

• 不需要特別操作，只要不執行 herdr server stop，Claude Code 的 Process 就會持續存在，即使 Detach 也不受影響（官方已實作）。
• 若需要長時間任務（例如大型重構），建議搭配具名 Session（herdr --session <name>）方便日後精準 Reconnect。

13.3 如何觀察狀態

在 Herdr Client UI 中，含 Claude Code 的 Pane 會顯示對應狀態標籤（working/idle/blocked/done/unknown）。當 Claude Code 進入等待使用者確認工具呼叫、等待輸入的情境時，畫面特徵通常會被 Screen Manifest 規則辨識為 blocked（官方已實作，見第 22 章深入解析）。

13.4 如何重新 Attach

herdr --session <name>

畫面會恢復到 Detach 前的狀態，包含 Claude Code 當時的對話畫面（因為底層 PTY 緩衝被保留）。

13.5 如何處理 Blocked

1. 觀察 Pane 內畫面，確認 Claude Code 實際在等待什麼（權限確認／工具呼叫核准／輸入補充資訊）。
2. 直接在該 Pane 內以 Terminal Mode 輸入回應。
3. 若長時間無法處理，記錄此 Pane 的 ID（如 w1:p2），交接給其他同仁或排入待辦（見第 22 章 SOP）。

13.6 如何避免多個 Claude Code 修改同一份程式碼造成衝突

核心原則：不同 Claude Code 實例，應該在不同的 Git Worktree／不同的 Branch 中工作（建議架構，見第 23-24 章）。若多個 Claude Code Pane 共用同一份 working directory，容易發生：

• 兩個 Agent 同時寫入同一檔案造成互相覆蓋
• 一個 Agent 執行 git checkout 切換分支，影響另一個 Agent 正在編輯的檔案
• Build/Test 結果因為程式碼被另一個 Agent 同時修改而不穩定

13.7 Scenario：一人多 Claude Code 分工

一位工程師在同一個 Workspace 內開了三個 Pane，分別對應三個 Git Worktree（worktree/backend、worktree/frontend、worktree/test），各自啟動一個 Claude Code 實例，互不干擾地並行工作，最後在人類主控的 Pane 中執行 git diff／merge 整合。

13.8 AI Prompt 範例（Backend Agent，供 Claude Code 使用）

Role: Senior Backend Developer (Java 25 / Spring Boot 4.x)
Objective: 在 worktree/backend 分支中，實作 OrderService 的 REST API
Context: 既有系統為 Spring Boot 3.x，正進行升版至 4.x，需保持既有 API 相容
Input: src/main/java/.../OrderController.java、既有測試套件
Constraints:
  - 不得修改 frontend/、test/e2e/ 目錄下任何檔案
  - 所有變更需通過既有 JUnit 5 測試
  - 每完成一個邏輯單元即建立一次 git commit（不要一次巨大 commit）
Tasks:
  1. 分析既有 OrderController 邏輯
  2. 依 Spring Boot 4.x 相容性要求調整程式碼
  3. 補齊缺漏的單元測試
Expected Output: 可編譯、可測試通過的程式碼變更 + commit 歷程
Validation: mvn test 全數通過
Stop Conditions: 若發現需要修改資料庫 Schema，停止並回報，不擅自執行 migration

13.9 本章 Checklist 與小結

• 已在 Herdr Pane 中成功啟動 Claude Code 並觀察到狀態變化
• 已驗證 Detach/Attach 不影響 Claude Code 對話進度
• 已採用 Git Worktree 隔離多個 Claude Code 實例，避免衝突

14. GitHub Copilot CLI + Herdr 實戰

14.1 基本流程

GitHub Copilot CLI 同樣列於 Herdr 官方支援清單（官方已實作，agents 文件）。典型工作流程：

flowchart TD
    A["Copilot CLI 啟動"] --> B["分析需求"]
    B --> C["修改程式"]
    C --> D["執行測試"]
    D --> E["Git diff 檢視"]
    E --> F["人類 Review / Commit"]

# 在 Pane 內啟動（實際指令名稱依官方 GitHub Copilot CLI 安裝方式而定）
copilot

14.2 與 Claude Code／Codex 共存

在同一個 Workspace 中，Copilot CLI 通常適合承擔「測試撰寫」「Code Review」「輕量修改」等任務，與負責主要架構/實作的 Claude Code 或 Codex 分工（建議架構，依團隊實務調整）。共存時同樣建議遵守「一個 Agent 一個 Pane」「不同 Agent 不共用同一份 working directory 寫入」的原則（見第 12、23 章）。

14.3 Scenario：測試補強分工

在一次 Sprint 中，Claude Code 負責後端邏輯開發，Codex 負責前端元件開發，GitHub Copilot CLI 被指派專門在 test Tab 中，針對前後端的產出撰寫對應的單元測試與整合測試，並在完成後於自己的 Pane 內執行 git diff 供人類 Review。

14.4 AI Prompt 範例（Test Agent，供 Copilot CLI 使用）

Role: QA / Test Automation Engineer
Objective: 為 backend worktree 新增的 OrderService API 撰寫 JUnit 5 測試
Context: 使用 Spring Boot 4.x Test 框架，既有測試位於 src/test/java
Input: 新增/修改的 Controller 與 Service 類別
Constraints: 僅新增測試檔案，不修改生產程式碼
Tasks:
  1. 分析新增的 API 端點與商業邏輯分支
  2. 撰寫涵蓋正常路徑與邊界條件的測試
  3. 執行測試並回報覆蓋率
Expected Output: 新增的測試檔案 + 測試執行結果
Validation: mvn test 全數通過，新增程式碼測試覆蓋率達團隊標準
Stop Conditions: 若既有程式碼有明顯 Bug 導致測試無法通過，回報但不擅自修改生產邏輯

14.5 本章 Checklist 與小結

• 已確認 Copilot CLI 在 Herdr 中的狀態偵測正常
• 已與 Claude Code/Codex 建立清楚的任務分工邊界
• 已建立「先寫測試、人類 Review diff 再 commit」的流程

15. Codex + Herdr 實戰

15.1 基本流程

flowchart TD
    A["Codex 啟動"] --> B["分析 Issue / 需求"]
    B --> C["修改 Code"]
    C --> D["Run Test"]
    D --> E["Static Analysis"]
    E --> F["Git Diff"]

codex

Codex 同樣列於官方支援清單（官方已實作，agents 文件）。

15.2 與其他 Agent 分工

常見分工模式（建議架構）：Codex 負責前端元件開發或特定 Issue 導向的修復任務，Claude Code 負責架構規劃與後端核心邏輯，Copilot CLI 負責測試與 Review。三者各自在獨立 Pane／Worktree 中運作，透過人類在 Review Tab 中整合。

15.3 Scenario：Issue 導向修復

團隊將一批 GitHub Issue 指派給 Codex，在專屬 Workspace 的 codex-fixes Tab 中，依序處理每個 Issue：分析 → 修改 → 測試 → Static Analysis → 產生 diff，並在每個 Issue 完成後於 Pane 中留下摘要，供人類快速 Review 是否可以合併。

15.4 AI Prompt 範例（Frontend Agent，供 Codex 使用）

Role: Frontend Developer (Vue 3 / TypeScript / PrimeVue)
Objective: 修復 Issue #482：訂單列表分頁元件在資料為空時顯示錯誤
Context: 專案使用 Vue 3 + Pinia + PrimeVue DataTable
Input: src/components/OrderList.vue、相關 Pinia store
Constraints: 不修改後端 API 契約；遵循既有 Tailwind CSS 樣式規範
Tasks:
  1. 重現並定位錯誤原因
  2. 修正元件邏輯
  3. 補上對應的前端測試（若專案已有測試框架）
Expected Output: 修正後的元件程式碼 + 修復說明
Validation: 本地執行確認空資料情境不再報錯，既有測試不因此變更而失敗
Stop Conditions: 若需求涉及後端 API 變更，停止並回報，交由 Backend Agent 處理

15.5 本章 Checklist 與小結

• 已確認 Codex 在 Herdr 中可正常啟動與被偵測
• 已建立 Codex 與 Claude Code／Copilot CLI 的分工邊界
• 每個 Issue 修復流程都留有可供人類 Review 的 diff

16. Multi-Agent Software Development

16.1 總覽圖

flowchart TD
    Human["Human Architect"] --> Herdr["Herdr"]
    Herdr --> Claude["Claude Code"]
    Herdr --> Codex["Codex"]
    Herdr --> Copilot["Copilot CLI"]
    Claude --> Code["Code"]
    Codex --> Test["Test"]
    Copilot --> Review["Review"]

（建議架構：以下四種模式為本手冊依 Herdr 的 Multi-Pane／Multi-Agent 能力歸納之企業實務模式，非官方文件明訂之「官方模式」）

16.2 Pattern A：Parallel（平行分工）

Agent A → Frontend
Agent B → Backend
Agent C → Test
Agent D → Security

適用情境：任務之間相依性低，可以真正同時進行。優點是總時程最短；風險是需要嚴格的 Git Worktree 隔離（見第 24 章），否則容易互相干擾。

16.3 Pattern B：Sequential（序列接力）

Architect
   ↓
Developer
   ↓
Tester
   ↓
Reviewer

適用情境：任務之間有明確先後依賴（例如必須先有架構設計才能實作）。優點是每個階段輸出明確、容易插入人類審查點；風險是總時程較長。

16.4 Pattern C：Reviewer（交叉驗證）

Agent A → Implementation
Agent B → Review
Agent C → Security Review

適用情境：對程式碼品質/安全性要求高的場景，讓不同 Agent（甚至不同廠商的 Agent）互相檢查彼此的產出，降低單一 Agent 的盲點風險。

16.5 Pattern D：Research + Implementation（研究先行）

Research Agent
      ↓
Architecture Agent
      ↓
Implementation Agent
      ↓
Test Agent

適用情境：面對不熟悉的 Legacy 系統或新技術導入前，先讓一個 Agent 專注做研究/現況調查，產出給後續 Agent 使用的知識基礎，常見於第 19 章逆向工程場景。

16.6 四種模式比較

16.7 Scenario：混合模式的真實案例

多數企業實務並非單一套用一種模式，而是混合使用：先用 Research + Implementation 模式讓一個 Agent 完成逆向工程與架構設計，再用 Parallel 模式讓多個 Agent 同時開發不同模組，最後用 Reviewer 模式做交叉安全審查（建議架構，第 53 章會提供完整端到端範例）。

16.8 本章 Checklist 與小結

• 能依任務相依性判斷該用 Parallel 還是 Sequential
• 高風險程式碼已導入 Reviewer 交叉驗證模式
• 面對不熟悉的系統，優先採用 Research + Implementation 模式

17. Web Application 開發實戰

17.1 技術 Stack 與 Herdr 的關係

重要澄清：以下技術 Stack 本身與 Herdr 沒有直接整合關係——Herdr 不會知道你用的是 Vue3 還是 React、Spring Boot 還是 Quarkus。Herdr 的角色是承載執行這些技術 Stack 開發工作流程的 AI Coding Agent 之 Runtime／Workspace 層（建議架構，避免過度宣稱）。

本手冊示範採用的企業技術 Stack（如需深入學習，請參閱本 Repository 對應手冊）：

17.2 開發流程中 Herdr 的角色

flowchart LR
    Herdr["Herdr Workspace"] --> Arch["Architecture Pane<br/>(Claude Code)"]
    Herdr --> FE["Frontend Pane<br/>(Codex)"]
    Herdr --> BE["Backend Pane<br/>(Claude Code)"]
    Herdr --> DB["Database Pane<br/>(Copilot CLI)"]
    Herdr --> Test["Test Pane<br/>(Codex)"]
    Herdr --> Sec["Security Pane<br/>(Claude Code)"]
    Herdr --> Rev["Review Pane<br/>(Copilot CLI)"]

Herdr 提供的是圖中每一個 Pane 的執行環境與狀態可視化；每個 Pane 內實際執行的 mvn、npm、git、AI Agent 指令，都是既有工具鏈本身的能力，不是 Herdr 提供的功能。

17.3 Scenario：一個 Sprint 的實際運作

在一個雙週 Sprint 中，團隊在 bank-web-platform Workspace 內，依 Pattern A（Parallel）分配任務：Claude Code 負責後端 API、Codex 負責前端頁面、Copilot CLI 負責測試撰寫，三者在各自的 Git Worktree 中並行；Sprint 中段每天早上，人類在 Review Tab 檢視前一天各 Agent 的 commit 與 diff，處理 Blocked 狀態的 Agent；Sprint 結尾切換為 Sequential 模式，由 Claude Code 進行整合測試前的最終 Review。

17.4 AI Prompt 範例（Architecture Agent）

Role: Software Architect
Objective: 為 bank-web-platform 專案設計符合 Hexagonal Architecture 的模組劃分
Context: Java 25 + Spring Boot 4.x 後端、Vue 3 + PrimeVue 前端、PostgreSQL 資料庫
Input: 現有需求規格文件、既有系統 ER Model（如有）
Constraints: 需與既有 [Spring boot 4.x 教學手冊] 中的架構慣例一致
Tasks:
  1. 定義 Domain / Application / Infrastructure 分層
  2. 定義模組間依賴方向（依 Hexagonal Architecture 原則，依賴指向 Domain）
  3. 產出各模組的職責說明文件
Expected Output: 架構決策文件（含 Mermaid 分層圖）
Validation: 架構文件經人類 Architect 審核通過
Stop Conditions: 若既有系統技術債過重無法直接套用 Hexagonal Architecture，先回報供人類決策

17.5 本章 Checklist 與小結

• 團隊已清楚 Herdr 是承載層，不是框架/技術選型工具
• 已依技術 Stack 分工建立對應 Workspace/Tab/Pane
• 已建立每日/每 Sprint 的人類 Review 節奏

18. Web Application Multi-Agent Workspace 範例

18.1 完整範例

bank-web-platform
│
├── 01-architecture
│     └── Claude Code
│
├── 02-frontend
│     └── Codex
│
├── 03-backend
│     └── Claude Code
│
├── 04-database
│     └── Copilot CLI
│
├── 05-testing
│     └── Codex
│
├── 06-security
│     └── Claude Code
│
└── 07-review
      └── Copilot CLI

（建議架構：此為本手冊示範用 Workspace 配置，實際專案應依團隊規模與任務性質調整）

18.2 使用建議

• 編號前綴（01-、02-……）有助於在 Tab 清單中維持固定順序，方便團隊成員快速定位。
• 06-security 建議獨立於 03-backend／02-frontend 之外，避免安全審查 Agent 的產出被開發中的變更污染（見第 34-35 章安全考量）。
• 07-review 是人類與 Agent 共用的整合點，建議只做 Review／Merge，不在此 Tab 直接進行大量開發。

18.3 本章 Checklist 與小結

• 已依此範例調整出符合自身專案規模的 Workspace 配置
• Security 與 Review Tab 已與開發 Tab 明確分離
• 團隊成員都理解每個 Tab 的職責與負責 Agent

19. 逆向工程 Software Development

19.1 整體流程

flowchart TD
    Legacy["Legacy System"] --> WS["Herdr Workspace"]
    WS --> RA["Reverse Agent"]
    RA --> AA["Architecture Agent"]
    AA --> DA["Documentation Agent"]
    DA --> DepA["Dependency Agent"]
    DepA --> MA["Modernization Agent"]
    MA --> TA["Test Agent"]

19.2 逆向工程十四步驟

1. Repository Discovery：確認原始碼結構、分支策略、建置工具
2. Build Discovery：確認如何從原始碼建置出可執行產物
3. Runtime Discovery：確認實際部署與執行環境（JVM 版本、Container、Server）
4. Dependency Analysis：盤點第三方套件、版本、已知漏洞
5. Architecture Discovery：還原分層架構、模組邊界
6. Database Analysis：還原 ER Model、Schema、Stored Procedure
7. API Analysis：盤點對外/對內 API 契約
8. UI Analysis：盤點前端頁面、元件、使用者流程
9. Business Logic Discovery：還原核心商業規則
10. Technical Debt Analysis：盤點技術債、風險點
11. Test Discovery：盤點既有測試覆蓋率與缺口
12. Security Analysis：盤點既有安全弱點
13. Documentation：產出還原後的架構/流程文件
14. Modernization Plan：產出現代化改造計畫

19.3 Agent 分工與 Workspace 配置

legacy-reverse-engineering
├── 01-repo-build-runtime   → Claude Code（步驟 1-3）
├── 02-dependency-arch      → Codex（步驟 4-5）
├── 03-database-api-ui      → Copilot CLI（步驟 6-8）
├── 04-business-techdebt    → Claude Code（步驟 9-10）
├── 05-test-security        → Codex（步驟 11-12）
└── 06-docs-modernization   → Claude Code（步驟 13-14）

（建議架構）

19.4 人類審查點與 Git 分支策略

Git 分支策略建議：逆向工程過程中不建立任何會影響現有系統的分支，所有 Agent 產出（文件、還原後的架構圖）建議先進入獨立的 docs/reverse-engineering 分支或文件庫，待人類確認後才視情況併入正式開發分支（建議架構）。

19.5 AI Prompt 範例（Reverse Engineering Agent）

Role: Reverse Engineering Analyst
Objective: 還原 legacy-order-system 的模組架構與資料庫 Schema
Context: 系統為 10 年以上歷史的 Java 7 應用，缺乏最新文件
Input: 完整原始碼、可存取的資料庫 Schema Dump（唯讀）
Constraints:
  - 僅分析，不修改任何原始碼
  - 不得對正式環境資料庫執行任何寫入/結構變更指令
Tasks:
  1. 列出所有模組與其職責
  2. 還原資料庫 ER Model
  3. 標記無法確定用途的程式碼區塊，交由人類確認
Expected Output: 架構還原文件（含 Mermaid ER Diagram）+ 待確認清單
Validation: 由資深工程師與原系統維護者共同審核
Stop Conditions: 若需要存取正式環境憑證才能繼續分析，停止並回報，不自行嘗試取得憑證

19.6 本章 Checklist 與小結

• 十四步驟逆向工程流程已對應到明確的 Agent 分工
• 每個關鍵審查點都有人類介入確認
• 逆向工程階段的 Git 策略不影響現有系統分支

20. Framework Upgrade

20.1 案例背景

以下以三個典型企業 Framework Upgrade 情境為案例（教學示範用虛構情境）：

Java 7 → Java 21 / Java 25
Spring Boot 3.x → Spring Boot 4.x
Spring Framework 6.x → 7.x
Jakarta EE migration

深入的框架升級技術細節請參閱：Java25升版教學、Spring boot 4.x升版教學、Spring framework 7.x 教學手冊、Jakarta EE 12 教學手冊。本章聚焦「如何用 Herdr 承載多 Agent 協作完成升級」，不重複框架本身的遷移細節。

20.2 Agent 分工流程

flowchart TD
    Disc["Discovery Agent"] --> Comp["Compatibility Agent"]
    Comp --> Mig["Migration Agent"]
    Mig --> Code["Code Agent"]
    Code --> Test["Test Agent"]
    Test --> Sec["Security Agent"]
    Sec --> Rev["Review Agent"]

20.3 Herdr 如何讓這些 Agent 長時間並行或序列執行

• 並行：Discovery Agent 完成盤點後，Compatibility Agent 與現有系統的 Test Agent（先跑既有測試建立 baseline）可以在不同 Pane 中同時進行。
• 序列：Migration Agent 必須等 Compatibility Agent 產出相容性報告後才能開始，這類強依賴步驟建議用 Sequential 模式（見第 16.3 節），並在 Herdr 中以不同 Tab 標示進度階段。
• 長時間運作：框架升級往往需要數天到數週，期間工程師會多次 Detach/Attach、甚至換裝置操作，Herdr 的 Session Persistence 正是支撐這種長週期任務的關镝能力（官方已實作）。

20.4 Scenario：Spring Boot 3.x → 4.x 升級

團隊在 spring-boot-upgrade Workspace 中，依序啟動 Discovery Agent（盤點目前使用的已棄用 API）→ Compatibility Agent（比對 Spring Boot 4.x Migration Guide）→ Migration Agent（產出升級計畫）→ Code Agent（實際修改程式碼，在獨立 Worktree 中進行）→ Test Agent（於升級後執行完整回歸測試）→ Security Agent（掃描新版本相依套件已知漏洞）→ Review Agent（產出最終 PR 摘要供人類審查）。

20.5 本章 Checklist 與小結

• 已確認升級案例的技術細節有對應既有框架手冊可參照
• 已規劃好哪些階段可並行、哪些必須序列
• 已利用 Herdr Session Persistence 支撐跨天的升級任務

21. Framework Upgrade Agent Workflow

21.1 十二階段總覽

（建議架構：此表為本手冊依 SSDLC 常見階段與 Multi-Agent 分工原則設計之範本，非官方固定流程）

21.2 Scenario：以 Herdr Tab 對應 Phase 進度

團隊將每個 Phase 對應一個 Herdr Tab（phase1-discovery ~ phase12-release），完成的 Phase 保留其 Pane（不關閉），方便日後追溯每個階段 Agent 的實際輸出與對話紀錄；進行中的 Phase 在團隊每日站會中被列為檢視重點，特別留意是否有 Pane 顯示 blocked 超過預期時間。

21.3 本章 Checklist 與小結

• 十二階段皆已對應明確 Agent、Pane、輸入輸出
• 標示「是」的人類核准關卡皆已落實，未經核准不得進入下一 Phase
• 每個關鍵 Phase 完成都有對應 Git Checkpoint

22. AI Agent Blocked State 深入解析

22.1 Agent 卡住不等於 Agent 崩潰

blocked 狀態只是 Herdr 依畫面特徵（或 Lifecycle Hook 回報）判斷 Agent 目前處於「需要外部輸入才能繼續」的狀態（官方已實作，見第 5.5 節）。這不代表 Agent Process 當機或錯誤，多數情況下 Agent 仍然存活，只是在等待。

22.2 常見 Blocked 原因

22.3 狀態決策圖

flowchart TD
    State["Agent State"] --> Working["working → 持續觀察即可"]
    State --> Idle["idle → 檢查是否任務已完成或閒置過久"]
    State --> Blocked["blocked → 需要人類介入"]
    Blocked --> Check{"確認原因"}
    Check -->|"等待輸入/核准"| Respond["直接回應"]
    Check -->|"Build/Test 失敗"| Diagnose["診斷根因後決策"]
    Check -->|"長時間無回應"| Escalate["升級交接給資深同仁"]

22.4 團隊 SOP

1. 每日固定時段（建議至少早/午/晚三次）巡查所有 Workspace 中是否有 blocked 狀態的 Pane。
2. 發現 blocked 後，5 分鐘內完成第一輪判斷（是否可自行處理）。
3. 若判斷需要跨團隊決策（例如涉及正式環境資料庫），30 分鐘內升級給對應負責人。
4. 每次處理 blocked 的原因與處理方式記錄下來，作為第 43 章常見錯誤清單的持續補充依據。

22.5 本章 Checklist 與小結

• 團隊已理解 blocked ≠ 崩潰
• 已建立巡查 blocked 狀態的固定頻率
• 已建立 blocked 升級處理的時效與責任歸屬

23. Herdr + Git

23.1 Multi-Agent 的 Git 分支規範

Agent A → branch-a
Agent B → branch-b
Agent C → branch-c

必須避免：

Agent A ─┐
Agent B ─┼── 共用同一份 working tree
Agent C ─┘

共用同一份 working tree 會導致：

• merge conflict：多個 Agent 同時修改重疊區域
• overwritten changes：後寫入的 Agent 覆蓋前一個 Agent 的變更
• broken build：某個 Agent 正在重構時，另一個 Agent 的 build 指令拿到不完整的中間狀態
• lost changes：未 commit 的變更被另一個 Agent 的操作（如 git checkout .）意外清除

23.2 Branch／Commit／Diff／Merge／Review／Rollback 搭配 Herdr

23.3 本章 Checklist 與小結

• 所有並行工作的 Agent 都有獨立 Branch/Worktree
• 沒有任何 Agent 直接對共用 working tree 進行寫入
• 每個 Agent 都被要求小步 commit

24. Herdr + Git Worktree + Multi-Agent

24.1 進階架構

Repository
│
├── main
│
├── worktree/frontend
│    └── Agent A (Codex)
│
├── worktree/backend
│    └── Agent B (Claude Code)
│
├── worktree/test
│    └── Agent C (Copilot CLI)
│
└── worktree/security
     └── Agent D (Claude Code)

24.2 為什麼 Worktree 架構比共用 Working Directory 更安全

Git Worktree 讓同一個 Repository 可以同時在多個實體目錄中，各自 checkout 不同分支且互不干擾（此為 Git 本身的原生能力，非 Herdr 提供，Source-confirmed）。搭配 Herdr 的 Pane 結構，可以做到「每個 Pane 對應一個獨立 Worktree 目錄，每個 Worktree 對應一個獨立 Branch，每個 Branch 由一個 Agent 負責」，徹底杜絕第 23.1 節列出的四種風險。

結論（建議架構）：對於 Multi-Agent 並行開發，Worktree 隔離架構在安全性上明顯優於共用 Working Directory，額外的磁碟與建置成本在多數企業開發環境中是可接受的代價。

24.3 Scenario：實務操作示意

# 示意：在既有 repo 中為不同 Agent 建立獨立 worktree
git worktree add ../worktree-backend backend-upgrade
git worktree add ../worktree-frontend frontend-upgrade

# 分別在 Herdr 的不同 Pane 中 cd 進對應 worktree 後啟動 Agent

24.4 本章 Checklist 與小結

• 已為每個並行 Agent 建立獨立 Git Worktree
• 已評估磁碟空間與建置成本是否可接受
• 已確認每個 Worktree 對應唯一負責的 Agent，避免混用

25. Remote Development

25.1 Herdr 與 SSH 的使用方式

flowchart TD
    Laptop["Developer Laptop"] -->|"SSH"| Server["Linux Development Server"]
    Server --> Herdr["Herdr"]
    Herdr --> Claude["Claude Code"]
    Herdr --> Codex["Codex"]
    Herdr --> Copilot["Copilot CLI"]

官方 how-to-work 文件描述的遠端使用模式包含：本機直接 herdr、先 ssh 進遠端主機再執行 herdr、以及 herdr --remote <host> 的 Thin Client 模式（官方已實作）。

25.2 斷線與恢復情境

25.3 具名 Session（Named Sessions）

當一台主機上需要同時存在多個彼此獨立的 Herdr Server（例如同一位工程師在同一台 Dev VM 上，分別維護「日常工作」與「side project」兩條互不干擾的 Workspace 集合）時，官方提供具名 Session 機制：每個具名 Session 各自擁有獨立的 Pane／Tab／Workspace／Socket 與 Runtime 狀態，但共用同一份全域 config.toml（官方已實作，persistence-remote 文件）。

herdr session list                    # 列出目前所有 Session
herdr session attach work             # 建立或連接名為 work 的 Session
herdr session attach side-project     # 另一個獨立 Session
herdr session stop work               # 停止（但不刪除）
herdr session delete side-project     # 停止並刪除

# 供腳本使用的機器可讀格式
herdr session list --json

企業應用建議（建議架構）：具名 Session 適合用來區分「不同機敏等級的專案」（例如一般開發 Session vs 涉及機敏資料的 Session），或區分「常駐長任務」與「臨時驗證」兩種不同生命週期的工作，避免全部塞進同一個預設 Session 導致難以管理。

25.4 Remote Attach：平台支援矩陣與設定

官方文件明確定義了 herdr --remote 這個 Thin Client 模式的平台支援範圍，企業規劃遠端開發架構前務必先確認這張矩陣，避免假設任意平台組合都可行（官方已實作，persistence-remote 文件）：

也就是說，Windows 只能是發起連線的 Client，不能作為被連線的 Server 端；企業若規劃「集中式 Windows Dev Server，讓多人以 --remote 連入」的架構，目前官方並不支援，必須改用 Linux/macOS 作為 Server 端（Source-confirmed，企業導入前務必實測確認）。

# 直接以主機名稱／使用者連線
herdr --remote workbox
herdr --remote ssh://you@server:2222

# 搭配 SSH config（建議寫法，避免每次輸入完整連線字串）

# ~/.ssh/config
Host workbox
  HostName server.example.com
  User you
  Port 2222

herdr --remote workbox

其他行為重點（官方已實作，persistence-remote 文件）：

• Herdr 會依序偵測遠端主機上既有的 herdr（PATH／Homebrew／mise／Nix 慣用安裝路徑），找不到才會詢問是否安裝到 ~/.local/bin/herdr；非互動式（non-interactive）執行環境下找不到就直接失敗，不會自動修改遠端主機，避免腳本化流程意外植入執行檔。
• --remote 預設沿用本機的鍵盤綁定（keybinding snapshot，於 attach 當下擷取），可用 --remote-keybindings server 改用遠端 Server 端設定；本機自訂的 Custom Command Keybinding 不會被送到遠端（因為那些指令本應在遠端主機執行才有意義）。
• 若本機與遠端平台相同，Herdr 會直接複製本機執行檔安裝；平台不同或透過 Homebrew／mise／Nix 安裝時，則會從 https://herdr.dev/latest.json 下載對應版本的 Release Asset。
• 可用 --session <name> 搭配 --remote 連到遠端主機上的具名 Session：herdr --remote workbox --session agents。
• Remote Attach 認證沿用一般 OpenSSH 機制；若金鑰有 passphrase 且執行環境無法互動輸入（CI、腳本、行動裝置終端），需先 ssh-add 將金鑰載入 ssh-agent（對應第 44 章官方 Troubleshooting 頁面的「Remote attach cannot authenticate」情境）。

25.5 Direct Terminal Attach 與 Bridge API

除了完整的 Workspace UI，Herdr 也提供「只附掛單一終端機」的輕量模式，適合只需要盯著特定 Pane、或需要把 Herdr 終端畫面橋接進第三方工具（例如企業內部監控面板）的情境（官方已實作，persistence-remote 文件）。

平台限制（v0.8.2 更新）：Direct Terminal Attach 在原生 Windows 上明確不支援（官方已實作，Windows 文件）。這不是「Preview 階段尚未驗證」，而是 GA 之後仍列在不支援清單中的功能缺口。需要此能力的企業（例如第 25.5 節末的資安唯讀稽核牆）必須把 Herdr Server 放在 Linux／macOS 上，見第 8.4 節決策矩陣。

# 依 Agent 名稱附掛
herdr agent attach reviewer

# 依 Terminal ID 附掛
herdr terminal attach term_abc123

# 同一終端同時只允許一個「可寫入」的 Direct Attach 使用者，用 --takeover 搶奪控制權
herdr terminal attach term_abc123 --takeover

對需要把終端畫面串接進自有工具（例如企業內部 Dashboard、錄影/稽核工具）的團隊，官方另外提供唯讀觀察與可寫入控制兩種 Bridge 指令，皆以換行分隔 JSON 傳遞畫面訊框（官方已實作，socket-api／persistence-remote 文件）：

# 唯讀：只接收畫面訊框（terminal.frame／terminal.closed），不佔用輸入權
herdr terminal session observe w1:p1 --cols 120 --rows 40

# 可寫入：額外可送出 terminal.input／terminal.resize／terminal.scroll／terminal.release
herdr terminal session control w1:p1 --takeover --cols 120 --rows 40

企業應用建議（建議架構）：terminal session observe 很適合用於「唯讀稽核牆」（例如資安團隊在獨立畫面上觀察多個 Agent Pane 但不介入操作），而不需要授予完整的 Herdr Client 存取權限。

若只是想略過 Server/Client 分離架構做單機除錯，可用 herdr --no-session 以單一 Process 執行（官方已實作），但這會失去 Session Persistence 的核心價值，僅建議用於偵錯或相容性測試，不建議作為日常工作模式。

25.6 適合企業 Server／Dev VM／Cloud VM 的情境

本手冊建議（建議架構）：對於需要長時間運作、隨時可能因網路不穩定而斷線的企業開發情境，建議將 Herdr Server 跑在企業內部 Dev VM 或 Cloud VM（須為 Linux 或 macOS，見第 25.4 節平台矩陣）上，開發者透過 SSH 或 --remote 連入，即可確保 Agent 任務不因個人裝置的網路狀況而中斷。

25.7 本章 Checklist 與小結

• 已確認團隊的 Herdr Server 運行位置（本機 vs 遠端 Dev VM），且遠端 Server 平台為 Linux／macOS
• 已驗證斷線重連後 Agent 任務可正常恢復
• 高風險/長時間任務優先安排在遠端 Server 上執行
• 已依專案機敏等級／任務生命週期規劃具名 Session 的使用方式
• 已確認團隊未將 Windows 主機規劃為 --remote 的連線目標
• 若有稽核/唯讀觀察需求，已評估 herdr terminal session observe 是否適用

26. Herdr API／Automation

26.1 三層整合介面

flowchart TD
    Human["Human"] --> CLI["herdr CLI"]
    CLI --> Sock["Herdr Socket API"]
    Sock --> Core["Session / Workspace / Pane / Agent"]

官方文件描述三種整合層級：Agent Skill、CLI Wrapper、原始 Socket API，且明確說明 CLI 本身就是 Socket API 的一層封裝（官方已實作，socket-api 文件）。

26.2 三個自動化原語（Primitive）

官方 agent-automation 文件將自動化能力拆成三個職責清楚的原語，選錯原語是企業自建自動化腳本時最常見的設計錯誤（官方已實作）：

一個 Pane 不論是否裝載 Agent 都存在；Agent 則是「目前在該 Pane 內執行、且被 Herdr 辨識出來的程序」。因此 agent start 要求該 Pane 已存在且處於可互動的 Shell 提示字元狀態，它本身不會建立、分割或搬移版面——版面規劃永遠是 Layout 原語的職責（官方已實作，agent-automation 文件）。

建立類指令一律回傳 JSON，腳本應該從回應中擷取 ID，而不是自行預測 ID 格式：

created=$(herdr workspace create --cwd ~/project --label api --no-focus)
pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')

split=$(herdr pane split "$pane_id" --direction right --no-focus)
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')

26.3 Agent 身分、啟動與控制介面

一個 Pane ID（如 w1:p2）定址「終端機所在位置」；一個 Agent 名稱（如 reviewer）則是該 Pane 內目前 Agent 的別名，需符合 [a-z][a-z0-9_-]{0,31} 且在所有存活 Agent 間唯一，Agent 結束/被釋放/被取代後別名即失效（官方已實作，agent-automation 文件）。Agent 指令可用唯一存活名稱或目前裝載該 Agent 的 Pane ID 定址。

# 在既有 Pane 中以指定 kind 啟動 Agent，並附加原生參數（-- 之後原封不動傳給該執行檔）
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4

--kind 目前支援的 Agent 值共 22 個（官方已實作，agent-automation 文件）：pi、claude、codex、gemini、cursor、devin、agy（Antigravity CLI）、cline、omp、mastracode、opencode、copilot、kimi、kiro、droid、amp、grok、hermes、kilo、qodercli、qwen（Qwen Code，v0.8.2 新增）、maki。

依「原始終端」或「Agent 語意」兩種需求，官方定義了對應的控制介面（官方已實作，agent-automation 文件）：

agent prompt 會送出文字加上編碼過的 Enter，並遵循終端當下的 bracketed-paste 模式，即使 Agent 目前正在 working 也可以送出；agent prompt --wait 若五秒內未觀察到狀態變化會回傳 agent_prompt_stalled，而非無限等待。agent wait／agent prompt --wait 預設接受 idle／done／blocked 任一狀態即視為完成，可重複 --until 指定多個精確狀態（例如 --until idle --until done）（官方已實作）。

一個實務 Recipe（官方已實作，agent-automation 文件；示意用途，實際請以當前版本 --help 為準）：

# 啟動一個 Code Review 用的 Codex 分身、送出審查任務、等待完成、讀取結果
split=$(herdr pane split --current --direction right --no-focus)
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000
herdr agent read reviewer --source recent-unwrapped --lines 120

26.4 Agent Skill：讓 Agent 自己操作 Herdr

除了「人類/腳本呼叫 CLI 操作 Herdr」，官方也提供反過來的路徑——讓在 Pane 內運行的 Agent（例如 Claude Code）自己學會操作 Herdr，藉此建立子 Pane、檢查其他 Agent 狀態、等待別的 Agent 完成（官方已實作，agent-skill 文件）：

# 安裝官方維護的 Agent Skill（透過 npx skills 工具）
npx skills add herdrdev/herdr --skill herdr -g   # -g 全域安裝；省略則僅安裝到目前專案

# 若已安裝 Herdr，可直接印出與該執行檔版本對應的 Skill 內容
herdr --skill

Skill 檔案的來源與安全前提（官方已實作，agent-skill 文件）：

• Skill 本體是一份 Markdown 指令檔，維護於官方 Repository 的 skills/herdr/SKILL.md，內容涵蓋 Pane ID、pane split／pane run／pane read／pane wait-output、agent wait、Workspace/Tab 指令與協作 Recipe。
• Skill 內建安全準則：只有當環境變數 HERDR_ENV=1（代表該 Agent 確實跑在 Herdr 管理的 Pane 內）存在時才允許操作；若未偵測到此變數，Agent 應停止並告知使用者「目前不在 Herdr Pane 內」，避免 Agent 誤操作它不擁有的 Session。
• Herdr 另外在 herdr.dev/agent-guide.md 提供性質不同的文件——那份是給「協助人類學習/設定/排除 Herdr 問題的 Agent」使用，與操作用的 Skill 檔案用途不同，不應混淆。

企業應用建議（建議架構）：對於已導入 Multi-Agent 協作模式（第 16 章）的團隊，替 Claude Code／Codex 安裝 Agent Skill 後，可以讓「架構 Agent」在完成設計後自行建立「實作 Agent」的 Pane 並下達任務，減少人類手動切換 Pane、複製貼上任務描述的操作成本；但仍應保留人類巡查機制（第 22 章），不應假設 Agent 之間的自動接力永遠正確。

26.5 實際可用範例

# 分割 Pane（示意，實際參數請以當前版本 herdr pane --help 為準）
herdr pane split w1:p1 --direction right

# 等待某個 Pane 內的 Agent 進入 done 狀態
herdr agent wait w1:p1 --until done

# 取得 Socket API 完整 Schema
herdr api schema --json

（以上指令為官方文件可查證之指令，官方已實作；具體參數請務必於實際安裝版本執行 --help 或 herdr api schema 再次確認，因版本演進可能調整）

26.6 Socket API 傳輸格式

Socket API 採本機 Unix Domain Socket（Windows 為 Named Pipe），以換行分隔的 JSON 訊息傳遞，每筆請求帶一個 id，回應以相同 id 對應（官方已實作，socket-api 文件）：

// Request（送出）
{"id": "req_1", "method": "ping", "params": {}}

// Response（收到）
{"id": "req_1", "result": {"type": "pong"}}

方法依領域分組：Server、Notification、Client、Session、Workspace、Worktree、Tab、Pane、Popup、Layout、Agent、Events（如 events.subscribe、events.wait）、Integrations、Plugins（官方已實作，socket-api 文件）。Schema 本身涵蓋原始請求、成功回應、錯誤回應、事件通知與訂閱事件五種型態，可用下列三種方式取得（官方已實作）：

herdr api schema                                    # 精簡摘要
herdr api schema --json                             # 完整 JSON Schema
herdr api schema --output herdr-api.schema.json      # 存成檔案，供 IDE/驗證工具使用

26.7 目前版本不提供 / 尚未確認支援

• 官方文件未提供公開的雲端/多使用者共享 API（僅本機 Socket）（Source-confirmed）。
• 完整 Socket API method 清單未逐一驗證，實際可用方法請以 herdr api schema --json 的即時輸出為準，不應假設本手冊列出的範例是完整清單（Source-confirmed）。

26.8 本章 Checklist 與小結

• 已理解 CLI 是 Socket API 的封裝，兩者能力對等
• 已理解 Layout／Pane／Agent 三個自動化原語的職責分工，未混用 Pane 指令操作 Agent 語意
• 自動化腳本已改用 herdr api schema 動態確認可用方法，而非硬編碼假設
• 已知悉目前僅提供本機 Socket，非雲端/跨主機 API
• 若團隊採用 Agent 自行操作 Herdr 的模式，已安裝 Agent Skill 並理解 HERDR_ENV=1 安全前提

27. Agent-to-Agent Automation

27.1 概念示意

flowchart TD
    AgentA["Agent A"] --> Tool["Herdr CLI / API"]
    Tool --> StartB["Start Agent B"]
    StartB --> DoneB["Agent B complete"]
    DoneB --> ContinueA["Agent A continue"]

（建議架構：此為概念示意，官方文件未提供一個「內建」的 Agent-to-Agent 自動化框架，實現此流程需要企業自行撰寫腳本呼叫 Herdr CLI/API）

27.2 三個層次的清楚區分

27.3 不要把 Herdr 描述成完整 Multi-Agent Orchestrator

Herdr 提供的是「等待」與「觀察」的原語（agent.wait、events.subscribe 等，官方已實作），這讓企業可以用少量腳本串接出簡單的自動化流程（例如：偵測 Agent A 完成後，用腳本呼叫 CLI 啟動 Agent B）。但這與具備完整任務編排、狀態機管理、重試補償邏輯的 Orchestration Framework 是不同量級的能力，不應混淆（見第 6.3 節）。

27.4 AI Prompt 範例（供人類撰寫串接腳本時參考的需求描述）

角色：Platform Engineer
任務：撰寫一支腳本，監聽 Herdr Socket API 的 agent 事件，當 Pane w1:p1
(Discovery Agent) 進入 done 狀態時，自動於 Pane w1:p2 啟動 Compatibility Agent。
限制：
  - 腳本需處理 Socket 連線中斷的重連邏輯（Herdr 本身不提供此保證）
  - 需記錄每次自動觸發的時間與觸發原因，供稽核使用
  - 若 Discovery Agent 進入 blocked 而非 done，腳本需通知人類而非自動繼續
輸出：腳本設計說明（虛擬碼即可，不需完整實作）

27.5 本章 Checklist 與小結

• 團隊清楚知道哪些自動化能力是 Herdr 原生提供，哪些需要自建
• 未把 Herdr 對外宣稱為「完整 Multi-Agent Orchestrator」
• 任何 Agent-to-Agent 自動化腳本都有失敗處理與人類通知機制

28. Plugin Architecture

28.1 Plugin 基本結構

Herdr Plugin 是一個包含 herdr-plugin.toml Manifest 的目錄，指令可以用任何語言撰寫（官方已實作，plugins 文件）。官方明確表示：「the entire Herdr CLI is the plugin API」——沒有另外獨立的 Plugin SDK，Plugin 就是透過呼叫 Herdr CLI 本身來擴充行為（官方已實作）。

28.2 Manifest 欄位

flowchart TD
    Herdr["Herdr"] --> Plugin["Plugin"]
    Plugin --> Action["[[actions]]"]
    Plugin --> Event["[[events]]"]
    Plugin --> Pane["[[panes]]"]
    Plugin --> Link["[[link_handlers]]"]

已確認的 Manifest 欄位（官方已實作，plugins 文件）：

28.3 安裝與管理

# 從 GitHub repo 安裝（可指定 subdir，讓一個 repo 內含多個可獨立安裝的 Plugin）
herdr plugin install owner/repo[/subdir]

# 本機開發模式（連結本地目錄，不執行 build，適合開發中反覆修改）
herdr plugin link /path/to/plugin

herdr plugin install 的流程是：clone 該 repo → 顯示內容預覽供使用者確認 → 執行 Manifest 中宣告的 [[build]] 指令 → 註冊 Plugin。若 build 失敗，Plugin 不會被註冊（官方已實作，plugins 文件）。完整管理指令見第 28.7 節。

28.4 Marketplace

Herdr Marketplace 會自動索引在 GitHub 上標記 herdr-plugin topic 的公開 repo，約每 30 分鐘更新一次；截至查證日期，Marketplace 尚未解析 Manifest 內容進行結構化展示（官方已實作，marketplace 文件）。

版本沿革提醒（Breaking Change）：v0.7.5（2026-07-21）將 Plugin 的安裝與啟用狀態從「依 Herdr Session 各自隔離」改為「全域跟隨目前作業系統使用者」（官方已實作，CHANGELOG）。企業若仍在使用 0.7.3 或更早版本、且曾經只在特定具名 Session 內安裝過 Plugin，升級至 0.7.5 以後需要重新安裝或重新連結該 Plugin。規劃升級 SOP（第 32.5 節）時應把此項納入檢查清單。

28.5 企業內部 Plugin 可能用途（建議架構）

• 將企業內部 Wiki／Ticket 系統（如 Jira）連結為 [[link_handlers]]，讓 Agent 輸出中的 Ticket 編號可直接點擊開啟。
• 建立 [[actions]] 快速動作，例如一鍵在目前 Pane 執行企業標準的 Pre-commit 檢查腳本。
• 建立 [[panes]] 自訂面板，顯示企業內部 CI Pipeline 的即時狀態。

28.6 本章 Checklist 與小結

• 已理解 Plugin = 目錄 + herdr-plugin.toml，指令可用任意語言撰寫
• 已確認欲使用/開發之 Plugin 的 min_herdr_version 相容性
• Windows 環境使用 Plugin 前，已確認該 Plugin 的 platforms 欄位確實宣告支援 Windows（平台整體已 GA，但個別 Plugin 未必跨平台）
• 已理解 [[startup]] 為一次性非同步初始化，未誤用為常駐監督機制（見第 28.7 節）

28.7 Plugin 執行環境與管理指令補充

第 28.1～28.4 節說明了 Plugin 的「結構」與「安裝」，本節補上企業自行開發 Plugin 時實際會用到的執行環境契約與完整生命週期指令（官方已實作，plugins 文件）。

28.7.1 注入的環境變數

Herdr 執行 Plugin 指令時會注入一組環境變數，這是 Plugin 與 Herdr 之間的主要介面——官方明確表示沒有獨立的 Plugin SDK，整個 Herdr CLI 就是 Plugin API（見第 28.1 節），因此 Plugin 的作法是「讀環境變數 → 呼叫 $HERDR_BIN_PATH 執行 CLI」。

為什麼要用 $HERDR_BIN_PATH 而不是直接寫 herdr：前者保證呼叫到的是「正在管理這個 Session 的那一份執行檔」，即使使用者的 PATH 中有多個版本、或 Herdr 尚未加入 PATH，Plugin 仍能正確運作（建議架構，依官方設計意圖之延伸說明）。

設計重點：config／state 目錄刻意與 Plugin 原始碼目錄分離。原因是透過 GitHub 安裝的 Plugin，其原始碼目錄是一份「由 Herdr 管理的 checkout」，可能因更新而被覆寫；使用者設定與執行期狀態放在獨立目錄才不會遺失（官方已實作）。企業自建 Plugin 時不應把設定寫回原始碼目錄。

28.7.2 Startup Hook 的正確語意

[[startup]] 是最容易被誤用的欄位。官方定義是：每個已啟用的 Plugin，在 Session 復原完成之後，非同步執行一次，執行時帶 HERDR_PLUGIN_EVENT=startup（官方已實作）。

常見誤用（建議架構）：把需要長期存活的背景服務（例如企業內部 CI 狀態輪詢程式）直接寫在 [[startup]] 裡並期待它一直跑著。正確作法是讓 Startup Hook 負責「啟動／確認該服務存在」這個一次性動作，服務本身的存活管理交給作業系統的服務機制（systemd、Windows Service）或 Herdr 的 [[panes]]。

28.7.3 Pane 放置位置與 id 命名限制

[[panes]] 的 placement 欄位可用值（官方已實作）：

Plugin id 的合法字元限於 ASCII 字母、數字，以及 .、:、_、-（官方已實作）。企業內部 Plugin 建議採用具命名空間的 id（例如 acme.security:precommit-check），避免與社群 Plugin 衝突（建議架構）。

28.7.4 完整管理指令

# 列出已註冊的 Plugin
herdr plugin list

# 手動觸發某個 Plugin 的 Action
herdr plugin action invoke <action-id>

# 查出某個 Plugin 的設定目錄位置（用於編輯其 config）
herdr plugin config-dir <id>

# 移除透過 GitHub 安裝的 Plugin
herdr plugin uninstall <id>

# 解除本機開發模式的連結（對應 herdr plugin link）
herdr plugin unlink <id>

uninstall 與 unlink 不可混用：uninstall 針對 GitHub 安裝（Herdr 管理的 checkout），unlink 針對 plugin link 連結的本機目錄。對本機連結執行 uninstall 不會有預期效果（官方已實作）。維運清理時（第 31.4 節）請先以 herdr plugin list 確認每個 Plugin 的來源類型。

28.7.5 Marketplace 的實際運作機制

Herdr Marketplace 並非一個需要送審的商店，而是一份自動索引：它掃描 GitHub 上標記 herdr-plugin topic 的公開 repo，Manifest 需位於 repo 根目錄或子目錄，索引約每 30 分鐘更新一次；發布者只需加上 topic 並提供安裝指令即可，且「一張 repo 卡片可以包含多個可獨立安裝的 Plugin」（官方已實作，marketplace 文件）。v0.8.2 針對 Manifest 探索與版本發布做了改善（官方已實作，v0.8.2 Release Notes）。

企業資安提醒（建議架構，呼應第 34 章）：正因為 Marketplace 是「自動索引公開 repo」而非「審核後上架」，被 Marketplace 收錄不代表經過官方安全審查。Plugin 在安裝時會執行 [[build]] 指令、執行期可透過 $HERDR_BIN_PATH 操作整個 Herdr Session，權限相當高。企業導入 Plugin 前應比照第三方相依套件的供應鏈風險流程處理：檢視原始碼、鎖定版本、優先自建內部 Plugin，並在第 31.4 節的月度清理中移除未使用者。

29. Agent Integration 深度

29.1 三種整合深度比較

flowchart LR
    Screen["Screen Detection<br/>(畫面特徵比對)"] --> Lifecycle["Lifecycle Integration<br/>(Agent 主動回報狀態)"]
    Lifecycle --> Plugin["Plugin Integration<br/>(深度客製化行為)"]

29.2 為什麼 Agent Integration 越深，Herdr 越能正確理解 Agent Lifecycle

Screen Detection 本質上是「看畫面猜狀態」，當 Agent CLI 更新其終端輸出樣式（例如新版本改變了進度顯示方式）時，既有規則可能失準，導致狀態誤判。Lifecycle Integration 則是 Agent 主動告知，不依賴畫面樣式，因此更穩定、更即時（官方已實作，agents 文件）。這不代表 Screen Detection 不可靠到不能用——它是官方對絕大多數 Agent（含 Claude Code、Codex、Copilot CLI）採用的預設機制，只是準確度的來源基礎不同。

29.3 以 Claude Code／Codex／GitHub Copilot CLI 為例

• Claude Code：狀態判斷目前為 Screen Detection（官方已實作，agents 文件），Herdr 透過辨識終端畫面中 Claude Code 特有的提示樣式、等待輸入樣式來判斷狀態。
• Codex：狀態判斷同樣為 Screen Detection。
• GitHub Copilot CLI：狀態判斷同樣為 Screen Detection。

重要修正／澄清：三者的狀態判斷均不在目前官方列出的 Lifecycle Authority 名單中，但這不代表三者完全沒有官方 Integration——官方確實提供 herdr integration install claude／codex／copilot 三個整合套件，只是這三個整合套件提供的是第 5.5 節定義的「Session Identity」能力（安裝後，Server 重啟可用 claude --resume <id>／codex resume <id>／copilot --resume=<id> 自動復原對話 Session），不會把狀態判斷升級為 Lifecycle Authority（官方已實作，integrations 文件）。企業導入時應清楚區分「這個整合裝了沒有」與「裝了整合之後狀態判斷準不準」是兩個獨立的問題。

官方整合套件安裝／解除安裝指令一覽（官方已實作，integrations 文件；--kind 值與此處整合名稱可能不同，請以官方文件為準）：

herdr integration install {pi|omp|claude|codex|copilot|devin|droid|kimi|opencode|kilo|hermes|qodercli|qwen|cursor|mastracode|antigravity-cli|grok}
herdr integration uninstall <同上任一名稱>
herdr integration status   # 檢查各整合套件的已安裝版本

Native Session Restore 所需最低整合版本（節錄企業最常用之 Agent；完整清單見官方 session-state 文件，官方已實作）：

版本不足、未安裝、或 Session 參照失效時，該 Pane 會在 Server 重啟後退回成一個位於原本工作目錄的全新 Shell，而不是自動復原對話（官方已實作）。

Qwen Code 標示說明（Source-confirmed）：v0.8.2 Release Notes 明載新增「Qwen Code detection for idle, working, and user-confirmation states with optional native session restore」，但官方文件未逐一列出其最低整合版本數字。企業導入前請以實際安裝版本執行 herdr integration status 取得當前要求值，勿引用本表推測數字。

29.4 自建/客製 Agent 的整合方式

若企業內部自行開發了 Coding Agent（非官方支援清單中的任何一種），仍可透過 Socket API／CLI 讓它主動回報 Lifecycle 狀態，取得與官方整合同等的權威地位，不需要被 Herdr 收錄進官方清單才能使用（官方已實作，integrations 文件）：

# 在 Herdr 管理的 Pane 內，Agent 進程可讀到 HERDR_ENV/HERDR_PANE_ID/HERDR_BIN_PATH/HERDR_SOCKET_PATH
# 主動回報自己進入 working 狀態
"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
  --source custom:my-agent --agent my-agent --state working

# Agent 結束時釋放狀態權威
"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \
  --source custom:my-agent --agent my-agent

實作重點（官方已實作，integrations 文件）：--state 僅回報 working／idle／blocked 等語意狀態，且僅在偵測到 HERDR_ENV=1 時才呼叫，確保這段整合邏輯在 Herdr 之外執行時自動變成無作用（no-op）；若回報可能不按順序抵達，應帶遞增的 --seq，Herdr 會忽略同一來源的過期序號。若只是想客製化顯示名稱/標題等呈現層資訊、而不想取得狀態權威，應改用 pane report-metadata（帶 --token／--state-label／--display-agent 等參數），這類 Metadata 只影響畫面呈現，不影響 Wait／通知等仍以語意狀態為準的行為。開源實例可參考社群專案 Prime Agent 的 Herdr Reporter 實作（Source-confirmed，第三方實作，非 Herdr 官方維護）。

企業應用建議（建議架構）：若企業已有內部維護的 Agent CLI（例如包裝自有 LLM API 的內部工具），與其等待官方收錄進支援清單，不如直接依上述方式自行整合，取得與 Pi／OMP 同等的狀態權威等級，比依賴 Screen Manifest 更準確、更不受畫面樣式改版影響。

29.5 本章 Checklist 與小結

• 已理解 Screen Detection 與 Lifecycle Authority 的準確度差異
• 已確認團隊主要使用的 Claude Code/Codex/Copilot CLI 目前狀態判斷為 Screen Detection，但可另外安裝官方整合取得 Session Identity（原生 Session 復原）能力
• 未把「可以在 Herdr 終端機裡執行」或「裝了官方整合套件」誤認為「一定具有 Lifecycle Authority」
• 若企業有自建 Agent，已評估透過 pane report-agent 自行整合取得狀態權威的可行性

30. Herdr Configuration

30.1 設定檔位置與格式

（官方已實作，configuration 文件）設定檔為 TOML 格式，不建立設定檔時 Herdr 會使用內建預設值運作（官方已實作）。

30.2 常用操作

# 印出目前完整的預設設定（可作為撰寫自訂設定的起點）
herdr --default-config

# 修改設定檔後，讓 Server 套用最新設定（不需重啟 Server）
herdr server reload-config

30.3 常見設定區塊（示意）

# 示意：非逐字官方預設值，實際欄位請以 `herdr --default-config` 輸出為準
[keys]
prefix = "ctrl+b"

[theme]
# 主題相關設定

[notification]
# 通知相關設定

（此區塊標示為「示意」，用途是說明設定檔的分區概念，並非官方原始 TOML 逐字內容；企業實際撰寫設定前，務必先執行 herdr --default-config 取得當前版本的真實預設值）

30.4 本章 Checklist 與小結

• 已確認自身平台對應的設定檔路徑
• 已執行 herdr --default-config 取得目前版本的完整預設設定作為基準
• 修改設定後已用 herdr server reload-config 驗證生效，而非重啟整個 Server
• 已對照第 30.5 節區塊總表，確認團隊共用設定範本涵蓋必要區塊

30.5 config.toml 主要區塊一覽

第 30.3 節的示意只說明了「設定檔有分區」這個概念。本節依官方 configuration 文件補上各區塊的實際職責與關鍵欄位，作為企業撰寫團隊共用設定範本時的對照表（官方已實作，configuration 文件）。

企業導入建議（建議架構）——上表中對企業最有價值的四個設定點：

1. [ui] window_title 搭配 {hostname}：多主機環境下，把主機名稱寫進視窗標題是成本最低的誤操作防護。工程師同時開著「本機」與「正式環境 Dev VM」兩個 Herdr 時，這一行設定可避免在錯誤的機器上執行破壞性指令（呼應第 34 章）。
2. [ui.toast] 選 "system"：讓 Agent 進入 blocked 時發出作業系統層級通知，工程師切到別的視窗做事時仍能被喚回，直接改善第 22 章「Blocked Agent 必須有人處理」的落實率。
3. [ui.sound] 的 per-agent 覆寫：多 Agent 並行時（第 16 章），不同提示音可讓人不看畫面就知道是哪一個 Agent 需要介入。
4. [[keys.command]] 的 shell 型別：把企業標準的 Pre-commit 檢查、內部掃描腳本綁成一個鍵位，降低「規範存在但沒人執行」的落差（呼應第 36 章治理）。

兩個必須遵守的查證原則：（一）本表僅列已於官方文件明確確認的核心欄位，不是完整清單；實際可用欄位、型別與預設值請以當前安裝版本的 herdr --default-config 即時輸出為準。（二）官方另提供可搜尋的 Config Reference 頁面（herdr.dev/docs/config-reference/），可依鍵名篩選瀏覽每個欄位的型別、預設值與允許值，撰寫企業設定範本時建議直接以該頁面交叉核對（官方已實作）。

31. 系統維護 SOP

31.1 維運週期總覽

31.2 Session Cleanup

# 列出目前所有 Session
herdr session list

# 停止/刪除不再需要的 Session
herdr session stop <name>
herdr session delete <name>

31.3 Process／磁碟檢查（建議架構，搭配作業系統既有工具）

# Linux/macOS：確認 herdr server process 資源使用狀況
ps aux | grep herdr

# 檢查 Herdr 設定/資料目錄佔用空間
du -sh ~/.config/herdr

31.4 Workspace／Agent／Plugin 清理

• 定期關閉已完成任務的 Workspace（herdr workspace close），避免清單過長難以辨識。
• 定期檢視已安裝 Plugin 是否仍在使用，移除未使用或未維護的 Plugin，降低供應鏈風險（見第 33 章安全考量）。

31.5 本章 Checklist 與小結

• 已建立 Daily/Weekly/Monthly 固定巡檢排程
• 已定期執行 Session/Workspace/Plugin 清理
• 已建立 Incident 發生時對應的處理流程入口（連結第 44 章）

32. Herdr 升級

32.1 herdr update

herdr update

此指令適用於透過官方 install.sh／install.ps1 安裝的情境（自我管理安裝）；若透過 Homebrew／mise／Nix 安裝，應改用該工具自身的更新機制（例如 brew upgrade herdr），而非 herdr update（官方已實作，agent-guide 文件）。

32.2 Stable／Preview Channel

# 查看目前 channel
herdr channel show

# 切換 channel（v0.8.2 起 Windows 亦支援雙向切換，不再有平台限制）
herdr channel set stable
herdr channel set preview

兩個通道的定位（官方已實作，Install 文件）：Stable 為預設且官方建議的一般使用通道；Preview 取自 master 分支的預發布建置，能較早拿到修正，但也可能出現回歸（regression）。

v0.8.2 升級注意事項：Windows 轉為 GA 之後，GA 之前就停留在 Preview 通道的既有安裝不會自動切回 Stable（官方已實作，Windows 文件）。企業若在 2026-08-19 之前已於 Windows 部署 Herdr，應在升級 SOP 中加入一步稽核：執行 herdr channel show，若顯示 preview 且該機器並非刻意要跟進預發布版本，則執行 herdr channel set stable 切回。詳見第 8.1 節。

32.3 不同安裝方式的更新策略比較

32.4 Server/Client 相容性與 Live Handoff

升級 Server 版本後，正在連線的舊版 Client 可能出現不相容情形；官方提供 --handoff 相關機制（herdr update --handoff）協助降低升級時的服務中斷（官方已實作，CLI 文件）。

平台限制（v0.8.2 更新）：Live Server Handoff 在原生 Windows 上明確不支援（官方已實作，Windows 文件）。本手冊初版寫的是「尚未完全驗證」，經 GA 後複查應更正為明確不支援——這是功能缺口而非驗證進度問題。原生 Windows 環境升級 Herdr 時，必須規劃明確的重啟時間窗口並事先通知使用者，不能假設可以無縫切換。需要無中斷升級能力的企業，應將 Server 置於 Linux／macOS（見第 8.4 節決策矩陣）。另需注意 Handoff 僅適用於 Herdr 自身更新器管理的安裝方式，Homebrew／mise／Nix 安裝無法使用（見第 5.3 節）。

32.5 Upgrade SOP Checklist

1. 確認目前版本：herdr --version
2. 查閱官方 Release Notes／CHANGELOG，確認本次升級是否有 Breaking Change
3. 備份重要設定檔（config.toml，見第 33 章）
4. 確認目前是否有正在運作中的重要 Session（避免升級過程中斷關鍵任務）
5. 執行對應安裝方式的更新指令
6. 驗證：herdr --version 確認版本已更新
7. 重新 Attach 既有 Session，確認 Agent 狀態顯示正常
8. 驗證關鍵 Agent（Claude Code/Codex/Copilot CLI）偵測功能正常
9. 驗證 Workspace／Plugin 是否正常運作
10. 若發現異常，依官方文件評估是否可 Rollback 到前一版本；若無法安全 Rollback，優先回報官方 Issue 並暫緩大規模推廣此版本

• 已完成上述 10 步驟並記錄結果
• 已通知團隊本次升級的版本異動與已知風險

32.6 本章 Checklist 與小結

• 已確認團隊各成員採用的安裝方式，並使用對應的更新指令
• 原生 Windows 環境升級已規劃明確的重啟時間窗口（Live Handoff 不支援，非「未驗證」）
• 已稽核 GA 前的 Windows 既有安裝是否仍停留在 Preview 通道，必要時已手動切回 Stable
• 已完整走過 Upgrade SOP Checklist 十步驟

33. Backup／Recovery

33.1 需要備份的項目

上表為概念總覽；「Detach/Attach」「Server 重啟」「Update（含/不含 --handoff）」四種情境下，Process／版面／近期畫面／Agent 對話各自是否保留的完整矩陣，見第 5.3 節。若企業需要「Server 重啟後仍能看到近期終端畫面」，可評估啟用 [experimental] pane_history = true（見第 5.3 節），但需注意這會把終端輸出（可能含機密）落地存檔，須與資安團隊確認可接受範圍後再啟用（見第 34 章）。

33.2 最重要的觀念：Session Recovery ≠ Code Recovery

flowchart LR
    A["Herdr Session Persistence"] -.-|"不等於"| B["Git / 程式碼備份"]

Herdr 的 Session Persistence，保存的是「終端機 Process 目前的執行狀態」（例如 Claude Code 對話畫面、尚未結束的 build 指令輸出），不是程式碼的版本控制備份。 一旦 Server Process 被終止（機器當機、herdr server stop、未預期的系統重啟），所有尚未 git commit 的變更就有遺失風險，與是否使用 Herdr 無關——這是任何終端機工具都存在的根本限制（建議架構，強調此概念以避免企業誤解）。

因此團隊規範必須明確要求：任何 Agent 完成一個有意義的邏輯單元，就應該 git commit，不要依賴 Herdr 的 Session Persistence 作為程式碼保護機制。

33.3 本章 Checklist 與小結

• 團隊已清楚區分 Session Recovery 與 Code Recovery 是兩件事
• config.toml 已納入個人/團隊設定備份流程
• 所有 Agent 均被要求小步 commit，不依賴 Session Persistence 保存程式碼

34. Security

34.1 風險分析

flowchart TD
    Human["Human"] --> Herdr["Herdr"]
    Herdr --> Agent["Agent"]
    Agent --> Shell["Shell"]
    Shell --> Prod["Production Resource"]

Agent 在 Herdr 的 Pane 中，實質上擁有與該 Pane 底層 Shell 相同的執行權限（Source-confirmed，Herdr 本身不額外限制 Agent 在 Shell 內可執行的指令範圍，權限邊界由 OS 使用者權限與 Agent 自身的工具使用限制決定）。這代表 Herdr 本身不是一個資安沙箱（Sandbox）產品，安全邊界主要仍需仰賴：作業系統層級的使用者權限管理、Agent 廠商自身的權限確認機制（如 Claude Code 的工具呼叫核准）、企業網路層級的存取控制。

34.2 風險項目清單

34.3 AI Coding Agent + Herdr Security Checklist

• 已確認 Agent 執行所在 Shell 的 OS 使用者權限，遵循最小權限原則
• 敏感憑證（SSH Key、API Key）未以明碼形式暴露在 Agent 可讀取的一般檔案中
• 所有第三方 Plugin 安裝前已完成來源可信度評估
• Server 若跑在遠端主機，該主機已納入企業既有伺服器資安管控範圍
• 未假設 Herdr 提供多使用者 Session 隔離保證
• 已針對「Agent 意外執行破壞性指令」情境建立備份與 Rollback 機制（見第 33 章）
• Production 相關憑證未配置在日常開發用 Herdr Session 可存取的範圍內（見第 35-36 章）

34.4 本章 Checklist 與小結

• 已完成上方 Security Checklist 全部項目
• 團隊已理解 Herdr 不是資安沙箱，權限邊界仍在 OS/Agent/網路層級
• 已建立 Plugin 安裝前的資安審查流程

35. Banking／Enterprise Environment

35.1 典型企業/銀行網路拓樸

flowchart TD
    PC["Developer PC"] --> VPN["VPN"]
    VPN --> Bastion["Bastion / Jump Server"]
    Bastion --> DevServer["Development Server"]
    DevServer --> Herdr["Herdr"]
    Herdr --> Agents["AI Coding Agents"]
    Agents --> Git["內部 GitLab / GitHub Enterprise"]
    Git --> CI["Build / Test"]

（建議架構：此為本手冊依常見銀行/大型企業網路架構歸納之示意圖，非官方文件內容）

35.2 需考量的企業限制

35.3 本章 Checklist 與小結

• 已確認 Herdr Server 部署位置符合企業網路拓樸與 Proxy 政策
• 已確認選用之 Agent CLI 的資料處理政策符合內部合規要求
• 開發環境與 Production 環境已有明確網路隔離

36. AI Coding Governance

36.1 治理流程

flowchart TD
    Approval["Human Approval"] --> Exec["Agent Execution"]
    Exec --> Test["Automated Test"]
    Test --> Scan["Security Scan"]
    Scan --> Review["Code Review"]
    Review --> Merge["Merge"]

36.2 禁止事項

除非企業明確授權，否則 Agent 不可直接存取或操作：

Production
Database（正式環境）
Production Server
Production Secret

這是本手冊反覆強調的紅線（建議架構，對應第 34-35 章的安全與企業環境考量）。Herdr 本身不會阻止 Agent 執行任何指令——這道防線必須由企業自行透過網路隔離、憑證管理、OS 權限設計來落實，不能假設 Herdr 或 Agent 廠商會自動阻擋。

36.3 本章 Checklist 與小結

• 治理流程圖已納入團隊開發規範文件
• Agent 執行環境已透過網路/權限手段確保無法直接存取 Production
• 所有 Merge 前都經過 Automated Test + Security Scan + Code Review

37. SSDLC + Herdr

37.1 各階段配置 Agent

flowchart TD
    Req["Requirements"] --> Arch["Architecture"]
    Arch --> Design["Design"]
    Design --> Impl["Implementation"]
    Impl --> Test["Test"]
    Test --> Sec["Security"]
    Sec --> Rev["Review"]
    Rev --> Release["Release"]
    Release --> Monitor["Monitor"]

37.2 Herdr 在其中負責什麼

Herdr 在 SSDLC 中的角色是橫向貫穿多個階段的 Runtime 層：它不定義流程本身（流程仍由企業 SSDLC 規範決定），而是提供「這些階段所需要的 Agent 執行工作能夠長時間、可觀察、可恢復地進行」的基礎設施（建議架構）。

37.3 本章 Checklist 與小結

• SSDLC 各階段已配置對應 Agent 與 Herdr Workspace/Tab
• 團隊理解 Herdr 是承載層，不是 SSDLC 流程本身
• Monitor 階段已釐清 Herdr 狀態資訊與正式監控系統的分工

38. Spec-Driven Development + Herdr

38.1 架構

flowchart TD
    Spec["Spec"] --> Plan["AI Planning"]
    Plan --> Herdr["Herdr"]
    Herdr --> A["Agent A"]
    Herdr --> B["Agent B"]
    Herdr --> C["Agent C"]
    Herdr --> D["Agent D"]
    A --> Impl["Implementation"]
    B --> Impl
    C --> Impl
    D --> Impl

38.2 Herdr 如何成為 Agent Runtime Layer

若企業採用 Spec → Plan → Tasks → Implementation → Test → Review 的 Spec-Driven Development 流程（可參考本 Repository spec-kit使用教學、OpenSpec使用教學），Herdr 承接的是「Plan 拆解出的 Tasks，交給哪些 Agent、在哪些 Pane 中執行」這一層：每個 Task 可以對應一個 Pane，Task 之間的依賴關係則對應 Sequential／Parallel 模式的選擇（見第 16 章）。

38.3 本章 Checklist 與小結

• Spec 拆解出的 Tasks 已對應明確的 Herdr Pane 配置
• Task 依賴關係已反映在 Sequential/Parallel 模式選擇上

39. Loop Engineering + Herdr

39.1 循環流程

flowchart TD
    Plan["Plan"] --> Implement["Implement"]
    Implement --> Run["Run"]
    Run --> Observe["Observe"]
    Observe --> Fix["Fix"]
    Fix --> Test["Test"]
    Test --> Plan

（可參考本 Repository 既有的 Loop Engineering 教學手冊 深入了解 Loop Engineering 方法論本身）

39.2 Herdr 如何提供長時間執行環境

Loop Engineering 強調「Plan → Implement → Run → Observe → Fix → Test → Repeat」的持續迭代循環，這類迭代往往需要數小時到數天不間斷運作。Herdr 的 Session Persistence 讓這個循環可以：

• 在 Agent 進入 working 狀態長時間執行時，工程師可以 Detach 去處理其他事務，不需要守在螢幕前
• 迭代過程中若發生 blocked（例如需要人類確認是否採用某個 Fix 方向），可即時被工程師發現並處理（見第 22 章）
• 跨天的迭代不會因為筆電關機、SSH 斷線而中斷（見第 25 章）

39.3 本章 Checklist 與小結

• Loop Engineering 的長時間迭代已受益於 Herdr 的 Session Persistence
• 迭代過程中的 blocked 狀態已納入日常巡查範圍

40. AI Agent Team Blueprint

40.1 企業級 AI Development Team 設計

AI Architect
AI Analyst
AI Developer
AI Frontend Developer
AI Backend Developer
AI DBA
AI Tester
AI Security Engineer
AI DevOps Engineer
AI Reviewer

（建議架構：以角色命名的 Agent，實際上是「指派給特定 Agent CLI 執行個體的職責標籤」，並非 Herdr 或任何 Agent 廠商提供的正式角色系統）

40.2 使用 Herdr 建立對應 Workspace

ai-dev-team
├── architect     → Claude Code（AI Architect）
├── analyst       → Claude Code（AI Analyst）
├── backend       → Claude Code（AI Backend Developer）
├── frontend      → Codex（AI Frontend Developer）
├── dba           → Copilot CLI（AI DBA）
├── test          → Codex（AI Tester）
├── security      → Claude Code（AI Security Engineer）
├── devops        → Copilot CLI（AI DevOps Engineer）
└── review        → Copilot CLI（AI Reviewer）

40.3 本章 Checklist 與小結

• 已依專案規模決定需要啟用哪些角色（非所有專案都需要全部十個角色）
• 每個角色的 Tab/Pane 職責已對團隊成員說明清楚

41. PM／SA／Architect／SD／PG／QA／DevOps／Security 使用方式

41.1 本章 Checklist 與小結

• 每個角色都清楚自己在 Herdr Multi-Agent 工作流程中的切入點
• PM/QA 等非技術/測試角色已能看懂 Agent 狀態標示的意義

42. Team Operating Model

Rule 1：一個 Agent 一個明確責任

避免讓單一 Agent 同時身兼架構設計與程式碼實作，職責混雜會提高 Review 難度。

Rule 2：一個 Workspace 對應一個 Project

避免跨專案混用同一個 Workspace，造成 Tab/Pane 難以歸屬。

Rule 3：重大修改一定建立 Git Checkpoint

任何 Framework Upgrade、大型重構，都必須在關鍵節點建立可回退的 Git Checkpoint（見第 21 章）。

Rule 4：Agent 不可直接覆蓋其他 Agent 的工作

透過 Git Worktree 隔離（見第 24 章）從架構上杜絕此風險，而非僅靠口頭約定。

Rule 5：Blocked Agent 必須有人處理

依第 22 章 SOP，建立巡查頻率與升級處理時效。

Rule 6：AI Agent 不可直接進 Production

依第 34-36 章，透過網路隔離與權限設計落實，而非僅靠信任 Agent 自律。

Rule 7：所有 AI 產生的重大程式碼必須經過 Test + Review

不因為是 AI 產出就降低品質把關標準，反而應該視為需要更嚴謹交叉驗證的產出（見第 16.4 節 Reviewer 模式）。

42.1 本章 Checklist 與小結

• 團隊已將以上 7 條規則納入正式開發規範文件
• 新進團隊成員 Onboarding 時已涵蓋這 7 條規則

43. 常見錯誤

44. Troubleshooting Decision Tree

flowchart TD
    Start["Herdr 無法啟動或行為異常"] --> Q1{"command not found?"}
    Q1 -->|"是"| Path["檢查 PATH 設定（見第 43 章 #1）"]
    Q1 -->|"否"| Q2{"Server 相關問題?<br/>(無法啟動/無法連線)"}
    Q2 -->|"是"| ServerDiag["執行 herdr status 診斷 Server/Session 狀態（見第 43 章 #5-7）"]
    Q2 -->|"否"| Q3{"Agent 相關問題?<br/>(未偵測/狀態錯誤)"}
    Q3 -->|"是"| AgentDiag["確認 Agent Process 是否存活、對照支援清單（見第 43 章 #2-4）"]
    Q3 -->|"否"| Q4{"Integration/Plugin 相關問題?"}
    Q4 -->|"是"| IntegDiag["檢查整合套件安裝狀態與版本相容性（見第 43 章 #12-13）"]
    Q4 -->|"否"| Q5{"平台特有問題?<br/>(Windows)"}
    Q5 -->|"是"| WinDiag["對照第 8.3 節 Windows Preview 已知限制"]
    Q5 -->|"否"| Escalate["蒐集完整 Log/重現步驟，回報官方 GitHub Issue"]

決策樹葉節點對應第 43 章常見錯誤清單之編號，建議兩者搭配使用：先用決策樹快速定位問題類別，再查表獲得具體 Symptom/Cause/Solution。

44.1 官方 Troubleshooting 頁面對照

修正說明：官方確實提供獨立 Troubleshooting 頁面（herdr.dev/docs/troubleshooting/），本手冊初版查證時誤判為「導覽未見獨立頁面」，特此更正。該頁面收錄以下八個具體情境，建議與上方決策樹、第 43 章常見錯誤表三者交叉引用（官方已實作，troubleshooting 文件）：

44.2 本章 Checklist 與小結

• 團隊成員已熟悉此決策樹的五個判斷分支
• 決策樹的葉節點已與第 43 章常見錯誤清單建立交叉連結
• 團隊已知悉官方 Troubleshooting 頁面的存在與網址，並非只能依賴本手冊自建的決策樹

45. 效能與資源管理

45.1 需要關注的資源面向

45.2 Multi-Agent 數量如何規劃

本手冊不提供沒有根據的硬性容量數字（例如「最多可以跑幾個 Agent」）。實際容量取決於：

• Agent 本身模型與運算成本（例如是否為需要大量 Token 推理的複雜任務）
• 工作負載類型（純文字對話 vs 需要頻繁執行 build/test 的任務）
• Repository 大小與 build/test 執行成本（大型 Monorepo 的 build 本身就會消耗大量 CPU/Memory，與 Herdr 無關）
• 執行機器本身的資源規格（CPU 核心數、記憶體容量）

建議做法（建議架構）：從小規模開始（例如 2-4 個 Agent 並行）驗證機器資源狀況，再依實際觀察到的 CPU/Memory 使用趨勢逐步擴大並行數量，而非依賴一個固定的「安全數字」。

45.3 Scenario：資源規劃實務

一個團隊在導入初期，於一台 16 核心/64GB 記憶體的 Dev Server 上，先以 4 個 Agent 並行測試一週，觀察到 CPU 使用率尖峰約 60%、記憶體尖峰約 40%，據此評估仍有擴充空間，逐步增加到 8 個 Agent 並行，並持續監控（建議架構，示範用資源規劃方法而非提供絕對數字）。

45.4 v0.8.2 對資源規劃的兩項影響

v0.8.2 有兩項變更會直接影響本章的容量估算基準，既有的資源規劃數據需要重新校準（官方已實作，v0.8.2 Release Notes）：

（一）Headless Server 預設虛擬終端尺寸由 80×24 提升為 120×40

這是一項容易被忽略但影響實際的變更。所謂 headless server 是指「Server 正在運行、但當下沒有任何 Client 附掛」的狀態——例如工程師 detach 後 Agent 仍在背景工作的整段期間。此時 Herdr 必須為每個 Pane 維持一個虛擬終端緩衝區，其尺寸即由此預設值決定。

建議做法（建議架構）：升級至 v0.8.2 後，重新量測一次 detached 狀態下每個 Pane 的記憶體佔用，再據以修正第 45.2 節的並行數量規劃；自動化腳本則優先改用 --source recent-unwrapped（取得未依畫面寬度換行的原始輸出）搭配明確的 --lines，讓腳本行為不受終端尺寸變動影響。

（二）多 Pane Session 的 CPU 回歸修正

v0.8.2 修正了一項「忙碌的多 Pane Session 造成 CPU 使用率異常偏高」的回歸問題（官方已實作）。若團隊曾在 v0.8.0／v0.8.1 期間量測過 CPU 基線並據此限制並行 Agent 數量，該基線在 v0.8.2 之後偏保守，建議重新量測後再決定是否放寬並行上限，避免以過時數據不必要地限縮團隊產能。

45.5 本章 Checklist 與小結

• 已從小規模並行數量開始驗證，逐步擴充
• 未依賴任何未經自身環境驗證的「建議並行數量」作為容量規劃依據
• 已建立定期清理長時間 Session scrollback 的習慣
• 升級 v0.8.2 後已重新量測記憶體基線（預設虛擬終端尺寸已變更為 120×40）
• 自動化腳本已改用 --source recent-unwrapped 搭配明確 --lines，不依賴終端尺寸假設
• 若 CPU 基線量測於 v0.8.0／v0.8.1 期間取得，已於升級後重新量測並檢討並行上限

46. 可觀測性

46.1 可觀測的狀態面向

flowchart TD
    AgentState["Agent State<br/>(working/idle/blocked/done/unknown)"] --> Obs["Observability 基礎"]
    WorkspaceState["Workspace State"] --> Obs
    ProcessState["Process State"] --> Obs
    Obs -.->|"不等於"| APM["完整 APM / Observability Platform"]

46.2 Herdr 狀態資訊 vs 完整 Observability Platform

Herdr 提供的 Agent State／Workspace State／Process State 資訊，可以作為 AI Software Development 過程中「人類是否需要介入」的第一層判斷依據（官方已實作，狀態機制見第 5.5 章）。但這不等於企業級 APM（Application Performance Monitoring）或完整 Observability Platform——Herdr 不提供 Build State／Test State 的結構化追蹤（這些仍由 CI/CD 工具本身負責）、不提供跨系統的分散式追蹤（Distributed Tracing）、不提供長期歷史指標儲存與告警規則引擎。

正確定位（建議架構，避免過度宣稱）：Herdr 的狀態資訊適合作為「開發階段、人機協作即時觀察」的輔助工具，若企業需要正式的 Build/Test/Deploy 可觀測性，仍應整合既有 CI/CD 與 APM 工具鏈，Herdr 不能取代這些系統。

46.3 本章 Checklist 與小結

• 團隊已理解 Herdr 狀態資訊的適用範圍與界線
• Build/Test/Deploy 的正式可觀測性仍由既有 CI/CD/APM 工具負責
• 未將 Herdr 對外宣稱為完整 Observability Platform

47. 企業導入架構與 Enterprise Rollout Plan

47.1 企業導入架構

flowchart TD
    Enterprise["Enterprise"] --> Dev["Developer"]
    Enterprise --> Platform["AI Platform Team"]
    Enterprise --> DevOps["DevOps"]
    Dev --> Herdr["Herdr"]
    Platform --> Herdr
    DevOps --> Herdr
    Herdr --> Claude["Claude Code"]
    Herdr --> Codex["Codex"]
    Herdr --> Copilot["Copilot CLI"]
    Claude --> CI["Git / CI / Test"]
    Codex --> CI
    Copilot --> CI

47.2 Enterprise Rollout 五階段

Phase 1：POC

• 目標：驗證 Herdr 基本功能與團隊接受度
• 人員：1-2 位資深工程師
• 技術：單機安裝，單一小型專案
• Security：無需特殊資安措施，使用非機敏測試 Repo
• Governance：無需正式治理流程
• KPI：是否成功完成一次完整 Detach/Attach 循環、團隊主觀滿意度
• Risk：低
• Exit Criteria：核心團隊認可 Herdr 帶來可感知的效率提升

Phase 2：Pilot Team

• 目標：驗證 Multi-Agent 協作模式在真實任務中的可行性
• 人員：一個 5-8 人小組
• 技術：導入 Git Worktree 隔離、基本 Workspace 規範
• Security：套用第 34 章 Security Checklist
• Governance：建立初版 Team Operating Model（第 42 章 7 條規則）
• KPI：Blocked 平均處理時間、Agent 產出通過 Review 比例
• Risk：中（需觀察是否有意外的資安/品質風險）
• Exit Criteria：Pilot 任務成功交付，無重大資安事件

Phase 3：Development Team

• 目標：擴大到整個開發團隊常態使用
• 人員：全體開發團隊
• 技術：導入遠端 Dev Server 部署（第 25 章）、正式維運 SOP（第 31 章）
• Security：導入第 35-36 章企業環境與治理要求
• Governance：正式治理流程上線，含人類核准關卡
• KPI：見第 48 章 KPI 設計
• Risk：中
• Exit Criteria：連續一個季度無重大 Incident，KPI 達到團隊自訂門檻

Phase 4：Department

• 目標：跨團隊/跨部門推廣
• 人員：整個工程部門
• 技術：標準化 Workspace 命名規範、集中式維運（第 31-33 章）
• Security：正式納入企業資安審查與稽核流程
• Governance：建立跨團隊治理委員會，制定企業級 AI Coding Governance 政策
• KPI：跨團隊 KPI 一致性、治理違規事件數
• Risk：中高（規模擴大後管理複雜度上升）
• Exit Criteria：治理政策正式生效並被各團隊遵循

Phase 5：Enterprise

• 目標：成為企業標準 AI Coding 工作流程的一部分
• 人員：全企業相關技術人員
• 技術：與企業 IT 治理、資安平台深度整合
• Security：納入企業年度資安稽核範圍
• Governance：納入企業正式 SOP 與教育訓練體系
• KPI：長期效率提升幅度、AI 產出品質趨勢
• Risk：需持續關注 Herdr 專案本身的成熟度演進（見第 1 章重要聲明：專案仍快速迭代中）
• Exit Criteria：企業內部形成穩定的教育訓練、維運、治理閉環

47.3 本章 Checklist 與小結

• 已依自身組織規模，對照上述五階段判斷目前所處階段
• 每個階段的 Exit Criteria 已明確定義並可被驗證
• 已認知 Herdr 專案本身仍在快速迭代，Enterprise 階段需持續追蹤版本演進

48. KPI

48.1 建議 KPI 清單

48.2 為什麼避免只用「AI 寫了多少行程式碼」

行數（Lines of Code）作為 KPI 存在的根本問題是：它會誘導出「寫多但品質差」「用大量樣板程式碼灌水」的行為，且完全無法反映 Blocked Time、Defect Rate、Rework Rate 等真正影響交付價值的面向。本手冊建議企業避免將行數作為主要 KPI（建議架構）。

48.3 本章 Checklist 與小結

• 已從上述清單中選定符合團隊現況的 3-5 個核心 KPI 起步
• 未將「AI 產出程式碼行數」列為主要 KPI
• KPI 蒐集方式已明確（部分可由 Herdr 狀態/Socket API 事件輔助蒐集，部分需搭配既有 CI/CD 系統）

49. Herdr 導入建議

適合使用

• 需要同時運用多個 AI Coding Agent、且任務需要長時間運作的開發情境
• 遠端/跨裝置開發，需要 Session 持久化與隨處恢復能力
• 需要清楚掌握多個 Agent 即時狀態，避免 Blocked 而不自知的團隊

不適合使用

• 僅偶爾單次呼叫單一 Agent 完成簡短任務的輕量使用情境（額外導入 Runtime 層的效益有限）
• 需要正式多使用者共享同一 Session 的協作模型（目前官方模型未提供此保證，見第 5.7 節）
• 期待 Herdr 直接提供完整 Agent Orchestration／CI/CD／Observability 能力的情境（需自行搭配其他工具，見第 6.3、27.3、46.2 節）

必須搭配

• Git／Git Worktree 分支策略（第 23-24 章）
• 企業既有 CI/CD 與 APM/Observability 工具鏈（第 46 章）
• 企業既有資安與權限管理體系（第 34-36 章）
• 明確的 Team Operating Model 與治理政策（第 36、42 章）

不應該做的事情

• 不應該讓 Agent 在未經隔離的共用 working directory 中並行工作（第 23-24 章）
• 不應該讓 Agent 執行環境具備直接存取 Production 的網路路徑（第 36 章）
• 不應該把 Session Persistence 當作程式碼備份機制（第 33 章）
• 不應該對外宣稱 Herdr 是完整 Agent Orchestrator／IDE／CI/CD Platform（第 55 章）

POC 建議

小規模（1-2 位工程師、1 個非機敏 Repo）驗證核心價值：Session Persistence、Agent 狀態可視化、Detach/Attach 恢復。

Production／企業建議

依第 47 章五階段逐步擴大，每個階段都有明確 Exit Criteria；正式導入前務必完成第 34 章 Security Checklist 全部項目。

Enterprise Governance 建議

建立跨團隊治理委員會，制定 AI Coding Governance 政策（第 36 章），並將 Herdr 專案版本追蹤（見第 1 章重要聲明）納入企業技術雷達的定期評估項目。

49.1 本章 Checklist 與小結

• 已對照「適合／不適合」判斷自身情境是否適合導入 Herdr
• 已確認導入前必須搭配的四項基礎設施均已到位
• 已將「不應該做的事情」四項紅線納入團隊規範

50. 最終企業標準 SOP

Herdr + AI Coding Agent Standard Operating Procedure

1. Install：依第 7-9 章完成安裝與驗證
2. Configure：依第 30 章完成 config.toml 設定與 herdr server reload-config 驗證
3. Create Workspace：依第 12 章企業規範建立專案 Workspace
4. Create Agent Pane：依「一個 Agent 一個 Pane」原則建立 Pane（第 12.1 節）
5. Start Agent：依第 13-15 章啟動 Claude Code／Codex／Copilot CLI
6. Assign Task：依第 52 章 Prompt 範本明確指派任務、限制與 Stop Conditions
7. Monitor：依第 22 章巡查 Agent 狀態，特別留意 blocked
8. Handle Blocked：依第 22.4 節 SOP 處理，超時升級
9. Test：Test Agent 或人類執行測試，確認品質門檻
10. Review：依第 16.4 節 Reviewer 模式進行交叉審查
11. Commit：小步提交，確保 Session 意外中斷時損失最小（第 33 章）
12. Merge：依第 36 章治理流程，經核准後合併
13. Detach：任務告一段落或需離開時 prefix+q
14. Reconnect：herdr 或 herdr --session <name> 重新接續
15. Maintain：依第 31 章執行 Daily/Weekly/Monthly 維運
16. Upgrade：依第 32.5 節 Upgrade SOP Checklist 執行版本升級

50.1 本章 Checklist 與小結

• 本 SOP 已張貼於團隊內部知識庫，供新進成員快速上手
• 每個步驟均已對應到本手冊詳細章節，可隨時查閱細節

51. Cheat Sheet

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Herdr Cheat Sheet
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【啟動】
herdr                          在目前目錄啟動 Herdr
herdr --session <name>         啟動/連接具名 Session
herdr --version                查看版本
herdr --help                   查看說明
herdr status                   查看 Server/Client 狀態

【Workspace / Tab / Pane】(CLI 子指令，實際旗標以 --help 為準)
herdr workspace list/create/get/focus/rename/close
herdr tab list/create/get/focus/rename/close
herdr pane split/swap/move/zoom/layout/resize/close

【Agent】
herdr agent list/get/read/explain/prompt/wait/rename/focus/start/attach
herdr agent start <name> --kind <kind> --pane <id> [-- 原生參數]
herdr agent prompt <name> "<text>" [--wait --until <state>]

【Pane 原始終端控制】
herdr pane run/send-text/send-keys/wait-output

【Remote / Session】
herdr session list/attach/stop/delete [--json]
herdr --remote <host> [--session <name>] [--handoff]
herdr terminal attach <id> [--takeover]
herdr terminal session observe/control <pane>

【Navigation（預設鍵位，Prefix = ctrl+b）】
prefix + c          新增 Tab
prefix + v           向右分割 Pane
prefix + minus       向下分割 Pane
prefix + h/j/k/l     Pane 間導覽
prefix + w           切換 Workspace
prefix + z           Zoom 目前 Pane
prefix + x           關閉 Pane
prefix + [           進入 Copy Mode
prefix + ?           顯示說明

【Detach / Attach】
prefix + q                     Detach（Server 持續運作）
herdr                          重新 Attach
herdr server stop              完全停止 Server

【Integration】
herdr integration install/status

【API】
herdr api schema [--json]      取得 Socket API Schema

【Update】
herdr update                   更新（自我管理安裝適用）
herdr channel show/set         查看/切換 Stable/Preview Channel

【Troubleshooting】
第 43 章常見錯誤表、第 44 章決策樹
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

（以上指令為官方文件可查證之指令集合，實際完整旗標請以當前安裝版本的 --help 輸出為準，官方已實作／Source-confirmed 混合，個別旗標細節可能隨版本調整）

51.1 本章 Checklist 與小結

• 已將本 Cheat Sheet 印出或存放於團隊常用工具列
• 新進成員第一週內已能不查手冊獨立完成基本操作

52. AI Agent Prompt 範本

以下每個範本均包含：Role／Objective／Context／Input／Constraints／Tasks／Expected Output／Validation／Stop Conditions 九個區塊，可直接依專案情境調整後交給 Claude Code／Codex／GitHub Copilot CLI 使用。

Architecture Agent Prompt

Role: Software Architect
Objective: 為指定專案設計符合企業架構規範的分層架構
Context: [填入專案技術 Stack 與既有架構限制]
Input: 需求規格文件、既有系統文件（如有）
Constraints: 需符合企業既有架構規範；不得引入未經核准的新技術元件
Tasks:
  1. 分析需求並定義模組邊界
  2. 產出分層架構圖（Mermaid）
  3. 標註各模組間依賴方向
Expected Output: 架構決策文件 + Mermaid 分層圖
Validation: 經人類 Architect 審核通過
Stop Conditions: 若既有系統限制導致無法採用建議架構，回報並提出替代方案供人類決策

Reverse Engineering Agent Prompt

Role: Reverse Engineering Analyst
Objective: 還原指定 Legacy 系統之架構與資料庫 Schema
Context: [填入系統年齡、技術背景、既有文件缺口]
Input: 完整原始碼、唯讀資料庫 Schema Dump
Constraints: 僅分析不修改；不得對正式環境執行任何寫入操作
Tasks:
  1. 盤點模組與職責
  2. 還原 ER Model
  3. 標記無法確定用途的區塊
Expected Output: 架構還原文件 + 待確認清單
Validation: 由原系統維護者確認還原結果正確
Stop Conditions: 需要正式環境憑證時停止並回報

Frontend Agent Prompt

Role: Frontend Developer (Vue 3 / TypeScript / PrimeVue)
Objective: [填入具體前端任務，例如修復特定 Issue 或實作特定元件]
Context: 專案採用 Vue 3 + Pinia + PrimeVue + Tailwind CSS
Input: 相關元件檔案、Pinia store、設計稿（如有）
Constraints: 不修改後端 API 契約；遵循既有樣式規範
Tasks:
  1. 分析需求/錯誤
  2. 實作/修正元件
  3. 補上對應測試（如專案已有測試框架）
Expected Output: 程式碼變更 + 說明
Validation: 本地驗證通過，既有測試不因此變更失敗
Stop Conditions: 若需求涉及後端 API 變更，停止並轉交 Backend Agent

Backend Agent Prompt

Role: Backend Developer (Java 25 / Spring Boot 4.x)
Objective: [填入具體後端任務]
Context: [填入既有系統版本與升級/開發背景]
Input: 相關 Controller/Service/Repository 類別、既有測試套件
Constraints: 保持既有 API 相容；每完成一個邏輯單元即 commit
Tasks:
  1. 分析既有邏輯
  2. 實作/調整程式碼
  3. 補齊缺漏測試
Expected Output: 可編譯、可測試通過的程式碼變更 + commit 歷程
Validation: mvn test 全數通過
Stop Conditions: 若需要修改資料庫 Schema，停止並回報

Database Agent Prompt

Role: Database Engineer
Objective: [填入具體資料庫任務，例如 Schema 分析或 Migration 腳本設計]
Context: [填入資料庫類型：Oracle/DB2/PostgreSQL/SQL Server]
Input: 現有 Schema、既有 Migration 歷史
Constraints: 不得直接對正式環境資料庫執行任何指令；僅產出腳本供人類審核執行
Tasks:
  1. 分析現有 Schema
  2. 設計 Migration 腳本（含 Rollback 腳本）
  3. 標註潛在風險（如大表變更的鎖表風險）
Expected Output: Migration 腳本 + Rollback 腳本 + 風險說明
Validation: 由 DBA 審核後方可於測試環境驗證
Stop Conditions: 涉及正式環境資料遷移，必須由人類 DBA 執行，Agent 不得代為執行

Test Agent Prompt

Role: QA / Test Automation Engineer
Objective: 為 [填入功能/模組] 撰寫測試
Context: 使用 JUnit 5（後端）／[前端測試框架，如有]
Input: 新增/修改的程式碼
Constraints: 僅新增測試檔案，不修改生產程式碼
Tasks:
  1. 分析程式碼分支與邊界條件
  2. 撰寫涵蓋正常路徑與邊界條件的測試
  3. 執行測試並回報結果
Expected Output: 測試檔案 + 執行結果
Validation: 測試全數通過，覆蓋率達團隊標準
Stop Conditions: 若發現既有程式碼 Bug，回報但不擅自修改生產邏輯

Security Agent Prompt

Role: Security Engineer
Objective: 對 [填入模組/功能] 進行安全審查
Context: [填入合規要求，例如銀行業資安規範]
Input: 相關原始碼、相依套件清單
Constraints: 僅分析與提出建議，不得自行修改程式碼
Tasks:
  1. 檢查常見漏洞類型（OWASP Top 10 相關）
  2. 檢查相依套件已知漏洞（CVE）
  3. 產出風險等級與修復建議
Expected Output: 安全審查報告（含風險等級分類）
Validation: 由資安團隊複核
Stop Conditions: 發現高風險漏洞時立即回報，不等待完整審查結束

Code Review Agent Prompt

Role: Senior Code Reviewer
Objective: Review [填入 PR/分支] 的程式碼變更
Context: [填入專案程式碼規範]
Input: Git diff、變更說明
Constraints: 僅提出審查意見，不直接修改程式碼
Tasks:
  1. 檢查程式碼品質與規範符合度
  2. 檢查是否有潛在 Bug 或邊界條件遺漏
  3. 檢查測試覆蓋是否充分
Expected Output: 審查意見清單（依嚴重度分類）
Validation: 由人類做最終合併決策
Stop Conditions: 若發現架構層級的重大問題，建議暫緩合併並回報 Architect

Framework Migration Agent Prompt

Role: Framework Migration Specialist
Objective: 將 [填入來源框架/版本] 升級至 [填入目標框架/版本]
Context: [填入既有系統背景，參照對應框架升級手冊]
Input: 現有原始碼、官方 Migration Guide
Constraints: 保持既有功能行為不變；每個模組獨立 commit，方便個別 Rollback
Tasks:
  1. 盤點已棄用/不相容 API
  2. 逐模組進行升級與相容性調整
  3. 執行完整回歸測試
Expected Output: 升級後程式碼 + 測試報告 + 已知風險清單
Validation: 完整回歸測試通過
Stop Conditions: 若升級涉及無法向下相容的行為變更，停止並回報供人類決策

Documentation Agent Prompt

Role: Technical Writer
Objective: 為 [填入系統/模組] 產出技術文件
Context: [填入目標讀者：新進工程師/架構師/維運人員]
Input: 原始碼、既有零散文件、Reverse Engineering Agent 產出（如有）
Constraints: 不得臆測未經確認的行為，不確定之處需明確標註
Tasks:
  1. 彙整現有資訊
  2. 產出結構化文件（含架構圖）
  3. 標註待確認/待補充事項清單
Expected Output: 技術文件 + 待確認清單
Validation: 由原系統負責人審核內容正確性
Stop Conditions: 若發現文件與實際程式碼行為明顯矛盾，優先回報而非自行猜測解讀

DevOps Agent Prompt

Role: DevOps Engineer
Objective: [填入具體 DevOps 任務，例如優化既有 CI Pipeline]
Context: [填入既有 CI/CD 工具：Jenkins/GitLab CI/GitHub Actions]
Input: 既有 Pipeline 設定檔
Constraints: 不得變更 Production 部署權限相關設定；變更需先於測試環境驗證
Tasks:
  1. 分析既有 Pipeline 瓶頸
  2. 提出優化方案
  3. 於測試環境驗證後產出變更 PR
Expected Output: Pipeline 設定變更 + 驗證結果
Validation: 由 DevOps 負責人審核後方可套用至正式 Pipeline
Stop Conditions: 涉及正式環境部署權限或密鑰管理變更，停止並回報，不得自行執行

52.1 本章 Checklist 與小結

• 已依專案實際情境填入各範本的方括號佔位內容
• 每個範本的 Stop Conditions 均已明確界定「何時必須交還人類決策」
• Prompt 範本已納入團隊共用的 Prompt Library

53. Herdr Agent Team 完整範例

53.1 案例目標

「將一個 Legacy Java Web Application 升級成 Java 25 + Spring Boot 4.x + Vue 3」

（教學示範用虛構情境，技術細節請參照 Java25升版教學、Spring boot 4.x升版教學）

53.2 Workspace 配置

legacy-to-modern
│
├── architect
│    └── Claude Code
│
├── reverse-engineering
│    └── Codex
│
├── backend
│    └── Claude Code
│
├── frontend
│    └── Codex
│
├── test
│    └── Copilot CLI
│
├── security
│    └── Claude Code
│
└── review
     └── Copilot CLI

53.3 端到端流程說明

1. Agent 如何啟動：依第 10 章 Quick Start 流程，在對應 Tab 的 Pane 中，先 git worktree add 建立各自獨立目錄（第 24 章），再啟動對應 Agent CLI。

2. Agent 如何分工：採 Pattern D（Research + Implementation，第 16.5 節）：reverse-engineering Tab 的 Codex 先完成第 19 章十四步驟中與程式碼/架構還原相關的分析，產出交給 architect Tab 的 Claude Code 進行現代化架構設計，再轉為 Pattern A（Parallel）由 backend／frontend 同時實作。

3. Agent 如何共享資訊：目前 Herdr 官方未提供 Agent 間直接的訊息傳遞機制（第 27 章），實務作法是將 Reverse Engineering／Architecture 產出的文件存放於 Repository 內固定路徑（如 docs/modernization/），供後續 Agent 在啟動任務時讀取作為 Context。

4. Git 如何管理：依第 23-24 章，每個 Tab 對應獨立 Worktree 與 Branch，review Tab 是唯一進行 Merge 決策的地方。

5. Herdr 如何管理：所有 Pane 集中於同一個 legacy-to-modern Workspace，人類透過 Herdr Client 一次總覽所有 Agent 狀態，決定巡查順序。

6. 人類在哪些地方介入：對照第 21 章十二階段表中標示「是」的人類核准關卡（Compatibility Analysis、Migration Design、Integration Test、Security Scan、Review）。

7. 如何處理 Agent Blocked：依第 22.4 節 SOP，每日固定巡查 legacy-to-modern Workspace 下所有 Pane 的狀態標示。

8. 如何測試：test Tab 的 Copilot CLI 在 backend／frontend 各自完成模組後執行對應測試（見第 21 章 Phase 7-8、10）。

9. 如何 Code Review：security Tab 的 Claude Code 與 review Tab 的 Copilot CLI 分別從安全與一般品質角度進行 Pattern C（Reviewer）交叉審查。

10. 如何完成升級：review Tab 產出的 PR 經人類最終核准後 Merge，並依第 21 章 Phase 12 建立 Release Tag。

53.4 本章 Checklist 與小結

• 案例中的七個 Tab 職責與負責 Agent 已對應清楚
• 人類核准關卡與第 21 章十二階段表一致
• Agent 間資訊共享採用固定文件路徑，而非假設存在即時通訊機制

54. 最佳實務總結

Top 10 Herdr Best Practices

1. 一個 Agent 一個 Pane，一個 Project 一個 Workspace（第 12 章）
2. 並行 Agent 一律搭配 Git Worktree 隔離（第 24 章）
3. 每個 Agent 任務都用第 52 章九區塊 Prompt 範本明確界定範圍與 Stop Conditions
4. 每日固定巡查 Blocked 狀態（第 22 章）
5. 長時間/高風險任務優先安排在遠端 Dev Server 上運行（第 25 章）
6. 小步 commit，不依賴 Session Persistence 保護程式碼（第 33 章）
7. 高風險程式碼採用 Reviewer 交叉驗證模式（第 16.4 節）
8. 定期執行 Session/Workspace/Plugin 清理（第 31 章）
9. 升級前完整走過 Upgrade SOP Checklist（第 32.5 節）
10. KPI 聚焦流程效率與品質，而非產出行數（第 48 章）

Top 10 Mistakes

1. 多個 Agent 共用同一份 working directory 寫入
2. 把 Session Persistence 誤當成程式碼備份
3. 把 Screen Detection 的狀態顯示誤解為 Agent 語意理解
4. 讓 Agent 執行環境具備直接存取 Production 的網路路徑
5. 把 Herdr 對外宣稱為完整 Agent Orchestrator/IDE/CI/CD Platform
6. 在 Windows Preview 版本上直接視為 Production Stable 使用
7. 忽略 Blocked 狀態長時間不處理
8. 未依安裝方式使用對應的更新指令（例如 Homebrew 安裝卻手動執行 herdr update）
9. 安裝來源不明的第三方 Plugin 未經資安審查
10. 以「AI 寫了多少行程式碼」作為主要 KPI

Top 10 Enterprise Recommendations

1. 依第 47 章五階段逐步擴大導入，不要一次全面推廣
2. 建立跨團隊 AI Coding Governance 委員會（第 36 章）
3. 正式導入前完成 Security Checklist 全部項目（第 34 章）
4. 建立 Workspace 命名與 Git Worktree 標準規範文件
5. 建立團隊共用的 Prompt Library（第 52 章範本為起點）
6. 持續追蹤 Herdr 專案版本演進，因其仍在快速迭代（第 1 章）
7. Production 隔離作為不可妥協的紅線（第 36 章）
8. 建立 KPI 儀表板，聚焦流程效率而非產出量（第 48 章）
9. 資深工程師優先試點，累積內部最佳實務後再全面推廣
10. 教育訓練涵蓋 PM/SA/QA/DevOps/Security 各角色（第 41 章），而非僅限開發人員

55. 架構師最終評估

Herdr 解決什麼問題？

它解決「AI Coding Agent 缺乏長時間、可觀察、可恢復運作環境」的問題——把終端機 Process 的存續與 Client 連線解耦，並在其上加了 Agent 狀態偵測（官方已實作）。

Herdr 沒有解決什麼問題？

它不解決「多 Agent 任務編排與依賴管理」（見第 6.3、27 章）、不解決「程式碼品質保證」（仍需 Test/Review/CI）、不解決「資安沙箱隔離」（見第 34 章）、不解決「跨系統可觀測性」（見第 46 章）。

Herdr 與 Agent Framework 的界線？

Herdr 不是 Agent Framework——它不提供建構 Agent 本身（Prompt 邏輯、工具呼叫、記憶體管理）的能力，這些能力屬於 Claude Code、Codex、Copilot CLI 等 Agent CLI 本身或其底層框架。

Herdr 與 Agent Orchestrator 的界線？

Herdr 提供「觀察」與「等待」原語（Socket API），但不提供任務佇列、DAG 編排、重試補償語意（第 6.3、27.3 節），複雜的多 Agent 編排仍需企業自建 Orchestration Layer。

Herdr 與 IDE 的界線？

Herdr 沒有程式碼編輯器、語法高亮、Debugger，開發者仍需 IDE 進行程式碼撰寫與除錯；Herdr 負責的是 Agent 實際執行工作的終端機環境（第 2.5 節）。

Herdr 與 tmux 的界線？

tmux 管理終端機 Pane 的存續，但不理解 Pane 裡面在跑什麼；Herdr 額外加上 Agent 語意（雖然是畫面樣式比對層次的語意，而非真正理解 Agent 意圖）與狀態追蹤（第 6.2 節）。

Herdr 是否適合 Enterprise？

適合，但需分階段導入（第 47 章），且須注意此專案仍在快速迭代，企業導入時應建立版本追蹤機制，不宜將任何當前細節視為長期不變的承諾。

Herdr 是否適合 Banking？

可以作為開發階段的 Runtime 工具導入，但必須嚴格落實第 35 章企業網路拓樸隔離與第 34 章安全 Checklist，尤其是 Production Isolation 與 Source Code Confidentiality 的要求；銀行業導入前建議先完成正式資安評估與合規審查。

Herdr 是否適合 Legacy Modernization？

適合，第 19 章逆向工程流程與第 53 章完整範例即示範了 Herdr 承載 Multi-Agent 逆向工程/現代化工作流程的具體方式，其長時間運作與狀態可視化能力特別適合這類週期長、需要多 Agent 協作的任務。

Herdr 是否適合 Framework Migration？

適合，理由同上，第 20-21 章提供了完整的十二階段 Agent Workflow 可直接參考套用。

Herdr 是否適合 Multi-Agent Development？

這是 Herdr 最核心的價值主張所在——第 16 章四種 Multi-Agent 工作模式，都是建立在 Herdr 的 Multi-Pane、狀態可視化能力之上才能有效落地。

Architecture Recommendation

對於已經在使用多個 AI Coding Agent（Claude Code / Codex / Copilot CLI）、
且面臨「多終端機難以管理、Agent 狀態不透明、斷線即中斷」痛點的團隊，
建議將 Herdr 導入為標準 Agent Runtime 層，並嚴格遵循：
  1. 一個 Agent 一個 Pane，搭配 Git Worktree 隔離
  2. 明確的人類核准關卡（治理紅線不可妥協）
  3. 分階段導入（POC → Pilot → Team → Department → Enterprise）
  4. 持續追蹤官方版本演進，不對外過度宣稱其能力邊界
在此前提下，Herdr 可以成為企業 AI Coding Agent 工作流程中，
承上啟下的關鍵基礎設施層。

（建議架構：此為本手冊基於前述 54 章分析之綜合建議，非官方立場）

55.1 本章 Checklist 與小結

• 已能清楚回答以上十一個界線問題
• 已依 Architecture Recommendation 形成自身組織的導入結論

56. 結語

Herdr 代表的是 AI Coding Agent 工具鏈演進中一個具體的分層需求：當 Agent 從「單次問答工具」演變成「可以長時間自主工作的協作者」，開發者需要的不再只是更聰明的 Agent，而是一個能讓這些 Agent 安全、透明、可恢復地運作的執行環境。

本手冊嘗試把 Herdr 官方文件中分散的能力描述，重新組織成一份可以直接支撐企業導入決策、日常操作、維運治理的完整教材。但如第 1 章重要聲明所述，Herdr 仍是一個快速演進中的年輕專案，本手冊所記錄的 CLI 指令、Agent 支援清單、Windows 支援狀態，都只是查證當下（2026-09-06）的快照。本次複查距初版僅三週餘，卻已出現「Windows 由 preview beta 轉為正式支援」這種足以推翻既有導入決策的變更（見 Appendix G），這正是上述提醒的最佳註腳——請務必以你實際安裝的版本與當下的官方文件為準。

對於準備導入的團隊，本手冊最後想強調的一句話是：先讓 Herdr 承載你已經在做的事情（讓現有的 Claude Code／Codex／Copilot CLI 工作流程更穩定、更可觀察），再逐步探索它能為 Multi-Agent 協作帶來的額外可能性；不要反過來，為了用 Herdr 而重新設計整套開發流程。

Appendix A：Command Reference

重要：以上為研究階段可查證之指令集合，非官方 CLI 之逐一窮舉完整清單。實際完整旗標與子指令，請務必以當前安裝版本執行對應指令加 --help，或執行 herdr api schema --json 取得即時 Schema 為準（見第 26 章）。

Appendix B：Configuration Reference

完整欄位清單請以 herdr --default-config 於當前版本之即時輸出為準，或瀏覽官方 Config Reference 頁面，本表僅列已於官方文件明確確認之核心項目。

Appendix C：Architecture Diagrams 索引

Appendix D：Glossary

Appendix E：Official References

• Herdr GitHub Repository
• Herdr 官方網站
• Herdr Documentation 首頁
• Herdr Installation
• Herdr Quick Start
• Herdr Concepts
• Herdr Agents
• Herdr How to Work
• Herdr Agent Guide
• Herdr Configuration
• Herdr Config Reference
• Herdr Keyboard
• Herdr Socket API
• Herdr Session State and Restore
• Herdr Persistence and Remote Access
• Herdr Integrations
• Herdr Agent Automation
• Herdr Agent Skill File
• Herdr Troubleshooting
• Herdr Plugins
• Herdr Marketplace
• Herdr Compare

Appendix F：Research Sources

Appendix G：版本異動對照（v0.8.0 → v0.8.2）

本附錄供已讀過本手冊舊版（2026-08-12 / v0.8.0 基準）的讀者快速比對本次更新了什麼、哪些舊認知需要作廢。若你是第一次閱讀本手冊，可略過本附錄。

G.1 讀者層級的 Breaking Change（必讀）

本次更新只有一項會讓舊版讀者的既有認知直接失效，但它影響範圍很大：

若你曾依舊版做過決策，請重新檢視這三件事：

1. 若曾因「Windows 是 Preview」而要求全團隊改用 WSL2 —— 該理由已不成立。請改依第 8.4 節的功能缺口判準重新評估（關鍵問題已不是「穩不穩」，而是「有沒有用到 Direct Attach／Live Handoff／作為 remote host」）。
2. 若曾在 GA 之前於 Windows 部署 Herdr —— 該安裝仍停留在 Preview 通道且不會自動切換，請執行 herdr channel show 稽核，必要時 herdr channel set stable（見第 8.1、32.2 節）。
3. 若升級 SOP 中寫著「Windows 的 Live Handoff 尚未驗證」—— 應更正為明確不支援，這是功能缺口而非驗證進度問題，必須規劃重啟時間窗口（見第 32.4 節）。

G.2 v0.8.2（2026-08-19）主要異動

以下依官方 Release Notes 分類整理，並標註本手冊對應已更新的章節（官方已實作，v0.8.2 Release Notes）：

Changed（行為變更）

Added（新增功能）

Fixed（修正，逾 50 項，節錄與企業相關者）

G.3 v0.8.1 說明

官方 Release 頁面未單獨展示 v0.8.1 的完整 Release Notes，其內容多已併入 v0.8.2 的累積說明中（Source-confirmed）。企業若需逐版差異，請直接查閱官方 CHANGELOG.md 或以 git log v0.8.0..v0.8.2 比對，勿以本附錄作為逐版稽核依據。

G.4 本手冊本次的自我更正

除了官方版本異動，本次複查也修正了兩處本手冊自身的問題：

後續維護提醒：Herdr 屬高頻迭代專案（v0.8.0 → v0.8.2 之間不到三週就出現了推翻既有聲明的 GA 變更）。本手冊建議企業至少每季複查一次官方 Release Notes 與 Windows 文件，並優先確認第 8.3 節的功能缺口清單是否收斂——那是本手冊中最可能隨版本失效的內容。