AI 程式設計教學中文版
官方教學中文版使用手冊

使用手冊

Hermes Agent 設定、工具系統、記憶、技能和訊息閘道器的中文使用入口，按問題定位能力邊界。

📖 本篇術語速查表
英文 / 縮寫中文一句話解釋
使用者指南user guideHermes 日常使用的功能組。
按需選pick按任務選該看哪項。
設定config功能的開啟和調整。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你搞清 Hermes 使用者指南這一組怎麼讀、按需用哪項。

你是 Hermes 使用者指南導航顧問。

【角色】
Hermes 使用者指南導航顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的具體步驟或示例，不停留在「建議」「考慮一下」這類空泛表述。

【輸入】
- 我的任務型別：___
- 想用的功能：___
- 現有設定：___
- 個人還是團隊：___
- 經驗水平：___

【工作流程】
1. 梳理使用者指南各項
2. 對應到我的任務
3. 給閱讀順序
4. 標出設定注意點
5. 給第一步

【輸出規範】
▌一、各項概覽
▌二、對應任務
▌三、閱讀順序
▌四、設定注意 + 第一步

【硬約束】
- 按任務選功能
- 設定改後驗證
- 貼合經驗水平
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法

Hermes 的使用手冊可以先壓成五個入口：設定、工具、記憶、技能、訊息閘道器。它們分別回答「在哪裡設定」「能做什麼」「記住什麼」「如何複用流程」「從哪裡遠端接入」。

先給結論：排障從 provider（推理服務商）、session（會話）、設定開始，不從 Gateway（訊息閘道器）、cron（定時任務）、MCP（模型上下文協議）或 skill（技能）開始。基礎閉環穩定後，再逐層啟用工具、記憶、技能和遠端入口——能力越多，錯位越容易擴散。

官方手冊覆蓋什麼

Hermes 官方 llms.txt 把 user guide（使用指南）拆成約 30 個子頁，可以分成五大類（先看下面的總覽，每項細節會在後續文章展開，不必現在記）：

  • 基礎對話與設定：CLI（命令列）、TUI（終端 UI）、configuration（設定）、models（模型）、sessions（會話）、profiles（設定檔）、git worktrees（git 工作區）、Docker backend（Docker 後端）、security（安全）、checkpoints（檢查點）。
  • 能力擴充套件：tools（工具）、skills（技能）、memory（記憶）、context files（上下文件案）、SOUL.md（人格檔案）、context references（上下文引用）、plugins（外掛）。
  • 自動化：cron（定時任務）、delegation（子代理委派）、kanban（看板）、goals（持久目標）、code execution（程式碼執行）、hooks（生命週期鉤子）、batch processing（批次處理）。
  • 多模態：voice（語音）、browser（瀏覽器）、vision（視覺）、image generation（影像生成）、TTS（語音合成）。
  • 訊息平臺：15+ 平臺的接入指南。

中文教學不把這些頁面平鋪成選單，而是按真實排障順序壓成 5 組：

組包含頁面先解決的問題
基礎執行CLI、TUI、configuration、models、sessions、profilesHermes 能不能穩定說話、恢復對話和切換模型
執行環境tools、toolsets、terminal backends、Docker、SSH、worktrees工具和命令在哪裡執行，是否可回復
長期上下文memory、memory providers、context files、SOUL.md、context references哪些事實進長期 prompt（系統提示），哪些按需引用
可複用能力skills、curator、plugins、MCP、ACP（代理上下文協議）、API server如何擴充套件能力且不汙染基礎環境
遠端與自動化messaging、cron、delegation、kanban、goals、hooks、batch遠端入口和後臺任務如何授權、審計和停止

這樣讀的好處是遇到問題能快速定位責任層，不會把「模型回答差」「命令執行錯」「訊息平臺沒授權」「memory 寫錯」混成一個含糊問題——四個問題的修復路徑完全不同。

五個入口

設定 Hermes Agent

讀懂 ~/.hermes/ 下 config.yaml、.env、auth.json、SOUL.md 各自管什麼，以及 provider 和 terminal backend 怎麼切換。

工具系統與終端後端

判斷要開哪些 toolsets（工具集），以及命令應該在本機、容器、遠端還是雲端執行——兩件事必須分開決策。

記憶系統

MEMORY.md、USER.md、凍結快照、session_search 和外部 memory provider 各自解決不同時間尺度的記憶問題——跨 session、跨任務、跨次對話。

技能系統

判斷什麼任務值得做成 skill，以及安裝外部 skill 前必須審查的金鑰與指令碼風險。

訊息閘道器與平臺接入

把 Hermes 接到 Telegram / Discord / Slack / Email 前，先理解 allowlist（允許名單）、DM pairing（私聊配對）和 chat session（聊天會話）。

按問題定位

不同症狀對應不同的「先去哪查」。把症狀和入口對上號，比從頭翻文件省時間得多：

flowchart LR
    S1["啟動失敗 / 模型不回<br/>key 不生效"] --> E1["📁 設定"]
    S2["命令不知道在哪跑<br/>工具許可權不清"] --> E2["🔧 工具系統"]
    S3["希望記住偏好<br/>專案規則 / 歷史任務"] --> E3["🧠 記憶系統"]
    S4["同一流程反覆做<br/>想做成可呼叫能力"] --> E4["📚 技能系統"]
    S5["接聊天平臺<br/>遠端入口 / 後臺"] --> E5["💬 訊息閘道器"]
    S6["MCP / ACP / API server<br/>provider routing"] --> CHK1{"基礎會話<br/>和 toolsets<br/>已穩定?"}
    S7["voice / browser<br/>vision / TTS"] --> CHK2{"目前工作流<br/>真需要媒體?"}
    CHK1 -- 否 --> E1
    CHK1 -- 是 --> EXT["✅ 擴充套件入口"]
    CHK2 -- 否 --> SKIP["⛔ 先不開"]
    CHK2 -- 是 --> EXT
    style EXT fill:#fde7c2,stroke:#d4761a
    style SKIP fill:#fde2e2,stroke:#c43d3d

文字版（圖載入失敗時看這個）：

  • 啟動失敗、模型不回、key 不生效 → 先查設定。
  • 命令不知道在哪裡執行、工具許可權不清楚 → 先查工具系統。
  • 希望 Hermes 記住偏好、專案規則或歷史任務 → 先查記憶系統。
  • 同一套流程反覆做，想變成可呼叫能力 → 先查技能系統。
  • 想把 Hermes 接到聊天平臺、遠端入口或後臺任務 → 先查訊息閘道器。
  • 需要 MCP、ACP、API server（API 伺服器）或 provider routing（推理服務商路由） → 先確認基礎會話和 toolsets 已經穩定。它們是擴充套件入口，不是排障入口——基礎不穩就開擴充套件，等於在裂縫上加壓。
  • 需要 voice（語音）、browser（瀏覽器）、vision（視覺）、image generation（影像生成）或 TTS（語音合成） → 先確認這些媒體能力真的屬於目前工作流。多數編碼任務並不需要一開始啟用媒體工具。

推薦排障順序

不要從最複雜的入口開始排查。穩定順序是：

  1. Provider 能不能完成普通對話。
  2. Session 能不能恢復。
  3. 設定檔和金鑰是否分開。
  4. Toolset 是否只開了目前任務需要的能力。
  5. Terminal backend 是否符合風險邊界。
  6. Memory 是否只存穩定事實。
  7. Skill 是否來自可信來源並已 hermes skills inspect（檢查命令）透過審查。
  8. Gateway、cron、background（後臺會話）、MCP 再逐項啟用。

Hermes 的複雜問題大多會退回三個基礎點：provider 是否穩定、session 是否可恢復、工具是否越權。先把這三點修對，再回頭看上層報錯——很多上層故障會自己消失。

啟用順序

把 Hermes 放進真實專案時，推薦按下面的順序做，每一步都要有可觀察結果（不只是"配完了"，而是"配完後我能看到什麼變化、出錯怎麼知道"）：

  1. Provider（推理服務商）：普通對話、模型切換和 token 計費路徑都能解釋清楚。
  2. Session（會話）：新建、繼續、搜尋、命名和清理 session 都能工作。
  3. Config（設定）：config.yaml、.env、auth.json、profile（設定檔）與專案 context 檔案（如 AGENTS.md、SOUL.md）分工清楚。
  4. Tools（工具）：只開目前任務需要的 toolset，並記錄高風險命令的批准方式（哪些命令需要按 Y 才執行，哪些走自動放行）。
  5. Backend（後端）：local、Docker、SSH、Daytona、Modal、Singularity、Vercel Sandbox 共 7 個選項只選一個主路徑先跑通；想加第二個之前先確認第一個穩定。
  6. Memory（記憶）：只儲存偏好、環境、約定和已驗證結論，不存記錄、金鑰或臨時細節——記憶是越用越髒的，寫入門檻要高。
  7. Skills（技能）：先使用內建或自建小 skill，跑穩了再考慮 Skills Hub 和外部 skill；任何外部 skill 安裝前都跑 hermes skills inspect 看指令碼和金鑰需求。
  8. Gateway（訊息閘道器）：從一個平臺開始（例如 Telegram 或 Slack），先用 allowlist 限定使用者；跑穩一個再加第二個。
  9. Automation（自動化）：cron、delegation、hooks、kanban、goals 最後啟用，並保留暫停入口——後臺任務必須能被一條命令停掉。

這不是保守，而是減少排障變數。Hermes 的優勢在組合能力，組合能力只有在基礎層穩定後才有價值；基礎不穩就堆功能，等於把噪聲放大。

最小健康狀態

一個可繼續擴充套件的 Hermes 設定應該滿足下面 8 條。可以用來對照自己目前裝機：

  • hermes --help 正常輸出。
  • hermes model 能列出和切換 provider。
  • hermes 能完成一次普通對話（輸入問題、收到合理回覆）。
  • hermes --continue 能恢復上一次 session。
  • ~/.hermes/.env（金鑰）和 config.yaml（設定）分工清楚，互不混寫。
  • terminal.backend 明確指定（local / docker / ssh / ...），不是預設值矇混。
  • toolsets 是按任務最小開啟——比如做編碼任務不開 browser 工具集。
  • Gateway 沒有在未設定 allowlist 的情況下上線（這條最容易踩坑：先開 Gateway 再設 allowlist = 在裸跑期間任何人都能命令你的機器）。

驗收清單

完成本節後，你應該能做一次最小驗收。把下面 10 條逐項確認（任何一項說不清，就別繼續疊加 MCP、cron、delegation 或多平臺閘道器）：

 1. hermes 能進入 CLI 或 TUI
 2. provider 能完成一次普通對話
 3. hermes --continue 能恢復上一輪
 4. 設定檔和金鑰檔案沒有混寫（金鑰不出現在 config.yaml 裡）
 5. 能解釋目前 toolset 清單（開了哪幾組工具集、為什麼）
 6. 能解釋 backend 的實際執行位置（命令到底在本機/容器/遠端跑）
 7. memory 裡沒有臨時記錄、token 或敏感資訊
 8. 能解釋每個已安裝 skill 的來源和作用範圍
 9. messaging 入口有 allowlist 或等效訪問限制
10. 自動化任務（cron / hooks / goals）有暫停命令、記錄和失敗告警

下一步

設定優先

新手先從設定頁開始，確認本機閉環能穩定執行——這是後面所有功能的地基。

回到原理篇

如果你還分不清這些能力之間的關係，先回到原理篇建立心智模型——花 30 分鐘比直接開幹省一整天排障。

官方資料

規劃 Hermes Agent 學習路徑

按經驗等級和使用場景選擇 Hermes Agent 文件閱讀順序，先跑通基礎閉環，再進入工具、記憶、訊息閘道器和自動化。

Hermes Agent 設定教學：config.yaml、.env 與終端 backend

講清 Hermes Agent 設定從哪裡開始：~/.hermes 目錄、config.yaml、.env、OAuth、設定優先順序、環境變數替換和七類 terminal backend。

本頁目錄

官方手冊覆蓋什麼五個入口按問題定位推薦排障順序啟用順序最小健康狀態驗收清單下一步官方資料