Section: Using Hermes · URL: https://hermesbible.com/docs/user-guide/profile-distributions

Profile Distributions：分享完整的 Agent

Profile distribution 將完整的 Hermes agent——人格、技能、排程任務、MCP 連線、設定——打包成一個 git repository。任何取得該 repo 的人都能用一行指令安裝整個 agent、原地更新，同時保留自己的記憶、session 與 API key。

如果 profile 是一個本地 agent，distribution 就是讓那個 agent 可以被分享的機制。

這代表什麼

在 distribution 出現之前，分享一個 Hermes agent 意味著寄給對方：

你的 SOUL.md
一份需要安裝的技能清單
你的 config.yaml（去掉機密資訊）
一段關於你接了哪些 MCP server 的說明
你設定的任何排程任務
設定環境變數的說明

……然後希望他們能正確組裝。每次版本更新或修正 bug 都要重複一次交接。

有了 distribution，以上所有內容都存在同一個 git repo 裡：

my-research-agent/
├── distribution.yaml    # manifest：名稱、版本、環境變數需求
├── SOUL.md              # agent 的人格 / system prompt
├── config.yaml          # 模型、temperature、reasoning、工具預設值
├── skills/              # 隨附的技能
├── cron/                # agent 執行的排程任務
└── mcp.json             # agent 連線的 MCP server

接收者只需執行：

hermes profile install github.com/you/my-research-agent --alias

就能取得整個 agent。他們填入自己的 API key（將 .env.EXAMPLE 複製為 .env），就可以執行 my-research-agent chat 或透過 Telegram / Discord / Slack / 任何 gateway 平台呼叫它。當你推送新版本時，他們執行 hermes profile update my-research-agent 即可拉取你的變更——他們的記憶和 session 完全不受影響。

為什麼是 git？

我們考慮過 tarball、HTTP archive、自訂格式。但都比不上 git：

作者零建置步驟。 推送到 GitHub；使用者安裝。沒有「打包、上傳、更新索引」的循環。
tag、branch 和 commit 本身就是版本控制系統。 一次 tag push 就能完成其他工具需要「打包 + 上傳 release」才能做的事。
更新就是一次 fetch。 不需要重新下載整個 archive。
完全透明。 使用者可以瀏覽 repo、檢視版本之間的 diff、開 issue、fork 來自訂。
私有 repo 免費使用。 SSH 金鑰、git credential helper、GitHub CLI 儲存的認證——你的 terminal 已設定好的任何驗證方式都能直接套用。
可重現性就是一個 commit SHA。 跟 pip 和 npm 記錄的是同一個東西。

代價是：接收者需要安裝 git。在 2026 年任何執行 Hermes 的機器上，這已經是既定事實。

什麼時候該使用 distribution？

適合的場景：

你在分享一個專業化的 agent——合規監控、程式碼審查、研究助理、客服機器人——給團隊或社群。
你把同一個 agent 部署到多台機器，不想每次手動複製檔案。
你在迭代一個 agent，希望接收者用一行指令就能取得新版本。
你把 agent 當成產品來打造——有主見的預設值、精選的技能、調校過的 prompt——供其他人作為起點使用。

不適合的場景：

你只想在自己的機器上備份 profile。 使用 hermes profile export / import——這就是它們的用途。
你想連 API key 一起分享。 auth.json 和 .env 被刻意排除在 distribution 之外。每個安裝者各自攜帶自己的認證。
你想分享記憶 / session / 對話紀錄。 那些是使用者資料，不是 distribution 的內容。永遠不會被傳送。

生命週期：作者 → 安裝者 → 更新

以下是完整的端到端流程。選擇你關心的那一方即可。

給作者：發佈 distribution

步驟 1——從一個可用的 profile 開始

像任何其他 profile 一樣打造並調校你的 agent：

hermes profile create research-bot
research-bot setup                    # 設定模型、API 金鑰
# 編輯 ~/.hermes/profiles/research-bot/SOUL.md
# 安裝技能、接上 MCP server、設定排程任務等
research-bot chat                     # 反覆測試直到滿意

步驟 2——加入 `distribution.yaml`

建立 ~/.hermes/profiles/research-bot/distribution.yaml：

name: research-bot
version: 1.0.0
description: "Autonomous research assistant with arXiv and web tools"
hermes_requires: ">=0.12.0"
author: "Your Name"
license: "MIT"

# 告訴安裝者這個 agent 需要哪些環境變數。這些會與安裝者的 shell
# 和已有的 .env 檔案做比對，這樣他們不會被已經設定好的金鑰干擾。
env_requires:
  - name: OPENAI_API_KEY
    description: "OpenAI API key (for model access)"
    required: true
  - name: SERPAPI_KEY
    description: "SerpAPI key for web search"
    required: false
    default: ""

就這樣。除了 name 之外，每個欄位都有合理的預設值。

步驟 3——推送到 git repo

cd ~/.hermes/profiles/research-bot
git init
git add .
git commit -m "v1.0.0"
git remote add origin git@github.com:you/research-bot.git
git tag v1.0.0
git push -u origin main --tags

現在這個 repo 就是一份 distribution。任何有權限的人都能安裝它。

注意

git repo 包含 profile 目錄中除了那些本來就被排除在 distribution 之外的所有內容：auth.json、.env、memories/、sessions/、state.db*、logs/、workspace/、*_cache/、local/。這些留在你的機器上。你也可以加入 .gitignore 來排除額外的路徑。

步驟 4——為版本發佈打上 tag

每次 agent 達到穩定狀態時，就更新版本並打上 tag：

# 編輯 distribution.yaml：version: 1.1.0
git add distribution.yaml SOUL.md skills/
git commit -m "v1.1.0: tighter research SOUL, add arxiv skill"
git tag v1.1.0
git push --tags

執行 hermes profile update research-bot 的接收者會拉取最新版本。

Repo 的實際結構

一份完整的已發佈 distribution：

research-bot/
├── distribution.yaml            # 必要
├── SOUL.md                      # 強烈建議
├── config.yaml                  # 模型、provider、工具預設值
├── mcp.json                     # MCP server 連線
├── skills/
│   ├── arxiv-search/SKILL.md
│   ├── paper-summarization/SKILL.md
│   └── citation-lookup/SKILL.md
├── cron/
│   └── weekly-digest.json       # 排程任務
└── README.md                    # 面向人類的描述（選填）

Distribution 掌管 vs. 使用者掌管

當安裝者更新到新版本時，有些東西會被替換（作者的領域），有些則保持不動（安裝者的領域）：

類別	路徑	更新時行為
Distribution 掌管	`SOUL.md`、`config.yaml`、`mcp.json`、`skills/`、`cron/`、`distribution.yaml`	從新的 clone 中替換
設定覆寫	`config.yaml`	實際上預設保留——安裝者可能已調校過模型或 provider。更新時加上 `--force-config` 可強制重置。
使用者掌管	`memories/`、`sessions/`、`state.db`、`auth.json`、`.env`、`logs/`、`workspace/`、`plans/`、`home/`、`_cache/`、`local/`	永不觸碰

你可以在 manifest 中覆寫 distribution 掌管的清單：

distribution_owned:
  - SOUL.md
  - skills/research/            # 只有我的研究技能；其他已安裝的技能保留
  - cron/digest.json

省略時，會套用上述預設值——這也是大多數 distribution 所需要的。

給安裝者：使用 distribution

安裝

hermes profile install github.com/you/research-bot --alias

過程中會：

將 repo clone 到臨時目錄。
讀取 distribution.yaml，顯示 manifest（名稱、版本、描述、作者、所需的環境變數）。
逐一檢查每個必要的環境變數，比對你的 shell 環境和目標 profile 已有的 .env。每個變數會標記為 ✓ set 或 needs setting，讓你清楚知道需要設定什麼。
詢問確認。加上 -y / --yes 可跳過。
將 distribution 掌管的檔案複製到 ~/.hermes/profiles/research-bot/（或 manifest 中 name 解析到的位置）。
寫入 .env.EXAMPLE，其中必要的金鑰已註解——複製為 .env 後填入即可。
加上 --alias 會建立 wrapper，讓你可以直接執行 research-bot chat。

來源類型

任何 git URL 都可以：

# GitHub 簡寫
hermes profile install github.com/you/research-bot

# 完整 HTTPS
hermes profile install https://github.com/you/research-bot.git

# SSH
hermes profile install git@github.com:you/research-bot.git

# 自架、GitLab、Gitea、Forgejo——任何 Git 主機
hermes profile install https://git.example.com/team/research-bot.git

# 使用你已設定的 git 認證安裝私有 repo
hermes profile install git@github.com:your-org/internal-bot.git

# 開發期間使用本機目錄（不需 git push）
hermes profile install ~/my-profile-in-progress/

覆寫 profile 名稱

兩位使用者想用不同的 profile 名稱安裝同一份 distribution：

# Alice
hermes profile install github.com/acme/support-bot --name support-us --alias
# Bob（同一份 distribution，不同的本地名稱）
hermes profile install github.com/acme/support-bot --name support-eu --alias

填入環境變數

安裝完成後，agent 的 profile 中有一個 .env.EXAMPLE：

# Environment variables required by this Hermes distribution.
# Copy to `.env` and fill in your own values before running.

# OpenAI API key (for model access)
# (required)
OPENAI_API_KEY=

# SerpAPI key for web search
# (optional)
# SERPAPI_KEY=

複製它：

cp ~/.hermes/profiles/research-bot/.env.EXAMPLE ~/.hermes/profiles/research-bot/.env
# 編輯 .env，貼上你自己的金鑰

已在你的 shell 環境中存在的必要金鑰（例如在 ~/.zshrc 中匯出的 OPENAI_API_KEY）在安裝時會被標記為 ✓ set——你不需要在 .env 中重複設定。

檢視已安裝的內容

hermes profile info research-bot

顯示：

Distribution: research-bot
Version:      1.0.0
Description:  Autonomous research assistant with arXiv and web tools
Author:       Your Name
Requires:     Hermes >=0.12.0
Source:       https://github.com/you/research-bot
Installed:    2026-05-08T17:04:32+00:00

Environment variables:
  OPENAI_API_KEY (required) — OpenAI API key (for model access)
  SERPAPI_KEY (optional) — SerpAPI key for web search

hermes profile list 也會顯示 Distribution 欄位，讓你一眼看出哪些 profile 來自 repo、哪些是手動建立的：

 Profile          Model                        Gateway      Alias        Distribution
 ───────────────    ───────────────────────────    ───────────    ───────────    ────────────────────
 ◆default         claude-sonnet-4              stopped      —            —
  coder           gpt-5                        stopped      coder        —
  research-bot    claude-opus-4                stopped      research-bot research-bot@1.0.0
  telemetry       claude-sonnet-4              running      telemetry    telemetry@2.3.1

更新

hermes profile update research-bot

過程中會：

從記錄的來源 URL 重新 clone repo。
替換 distribution 掌管的檔案（SOUL、skills、cron、mcp.json）。
保留你的 config.yaml——你可能已調校過模型、temperature 或其他設定。加上 --force-config 可覆寫。
永不觸碰使用者資料：記憶、session、認證、.env、logs、state。

不需要重新下載整個 archive。不會覆蓋你的本地設定。不會刪除你的對話紀錄。

刪除

hermes profile delete research-bot

刪除提示會在確認前顯示 distribution 資訊：

Profile: research-bot
Path:    ~/.hermes/profiles/research-bot
Model:   claude-opus-4 (anthropic)
Skills:  12
Distribution: research-bot@1.0.0
Installed from: https://github.com/you/research-bot

This will permanently delete:
  • All config, API keys, memories, sessions, skills, cron jobs
  • Command alias (~/.local/bin/research-bot)

Type 'research-bot' to confirm:

讓你在刪除 agent 時永遠不會不知道它的來源或無法重新安裝。

使用場景與模式

個人：跨機器同步同一個 agent

你在筆電上打造了一個研究助理。你希望工作站上也有同一個 agent。

# 筆電
cd ~/.hermes/profiles/research-bot
git init && git add . && git commit -m "initial"
git remote add origin git@github.com:you/research-bot.git
git push -u origin main

# 工作站
hermes profile install github.com/you/research-bot --alias
# 填入 .env。搞定。

在筆電上的任何迭代（git commit && push），用 hermes profile update research-bot 就能拉到工作站。記憶是每台機器各自獨立的——筆電記得自己的對話，工作站記得自己的，不會衝突。

團隊：發佈一個經過審查的內部 agent

你的工程團隊想要一個共享的 PR 審查機器人，帶有特定的 SOUL、特定的技能，以及每次 PR 都會跑過它的排程。

# 工程主管
cd ~/.hermes/profiles/pr-reviewer
# ... 打造並調校 ...
git init && git add . && git commit -m "v1.0 PR reviewer"
git tag v1.0.0
git push -u origin main --tags    # 推送到公司的內部 Git 主機

# 每位工程師
hermes profile install git@github.com:your-org/pr-reviewer.git --alias
# 用他們自己的 API 填入 .env（費用由他們自行承擔），.env.EXAMPLE 會提示需要哪些
pr-reviewer chat

當主管發佈 v1.1（更好的 SOUL、新技能）時，工程師們執行 hermes profile update pr-reviewer，幾分鐘內 everyone 就都在新版上了。

社群：發佈公開的 agent

你打造了一個有新意的東西——可能是「Polymarket 交易員」或「學術論文摘要工具」或「Minecraft 伺服器運維助理」。你想要分享它。

# 你
cd ~/.hermes/profiles/polymarket-trader
# 在 repo 根目錄寫一份扎實的 README.md——GitHub 會在 repo 頁面顯示它
git init && git add . && git commit -m "v1.0"
git tag v1.0.0
# 發佈到公開的 GitHub repo
git remote add origin https://github.com/you/hermes-polymarket-trader.git
git push -u origin main --tags

# 任何人
hermes profile install github.com/you/hermes-polymarket-trader --alias

在社群媒體上分享安裝指令。嘗試的人會回報 issue 和 PR。如果有人想客製化，他們 fork 即可——用的是 everyone 都已經熟悉的 git 工作流程。

產品：發佈一個有主見的 agent

你打造了 Hermes 上層應用——可能是合規監控框架、客服平台、特定領域的研究平台。你想要把它當產品來分發。

# distribution.yaml
name: telemetry-harness
version: 2.3.1
description: "Compliance telemetry harness — monitors and reviews regulated workflows"
hermes_requires: ">=0.13.0"
author: "Acme Compliance Inc."
license: "Commercial"

env_requires:
  - name: ACME_API_KEY
    description: "Your Acme Compliance license key (email support@acme.com)"
    required: true
  - name: OPENAI_API_KEY
    description: "OpenAI API key for model access"
    required: true
  - name: GRAPHITI_MCP_URL
    description: "URL for your Graphiti knowledge graph instance"
    required: false
    default: "http://127.0.0.1:8000/sse"

你的客戶透過一行指令安裝；安裝預覽會明確告知他們需要準備哪些金鑰；你標記新版本的瞬間更新就推送出去；他們的合規資料（memories/、sessions/）永遠不會離開他們的機器。

臨時性：共享基礎設施上的一次性腳本

你是運維主管。你想要一個臨時 agent 來診斷 production 事故——一個內建正確工具和 MCP 連線的現成 SOUL——在接下來一週內跑在三位值班工程師的筆電上。

# 你
# 打造 profile，commit，推送到私有 repo
git push -u origin main

# 每位值班人員
hermes profile install git@github.com:your-org/incident-2026-q2.git --alias

# 事故解決——拆掉它
hermes profile delete incident-2026-q2

安裝-刪除循環的成本低到可以當作一次性的。

實用技巧

固定到特定版本

注意

Git ref 固定（#v1.2.0）已規劃但尚未包含在初始版本中——目前安裝會追蹤預設 branch。你可以用 hermes profile info <name> 追蹤已安裝的版本，在準備好之前暫不更新。

檢視目前版本 vs. 最新版本

# 你的已安裝版本
hermes profile info research-bot | grep Version

# 最新的上游版本（不執行安裝）
git ls-remote --tags https://github.com/you/research-bot | tail -5

更新時保留本地設定客製化

預設的更新行為已經會這麼做：config.yaml 會被保留。為了更安全，把你的本地調整寫到 distribution 不掌管的檔案中：

# ~/.hermes/profiles/research-bot/local/my-overrides.yaml
#（distribution 永不觸碰 local/）

……然後在需要時從 config.yaml 或你的 SOUL 中引用它。

強制全新安裝

# 清除並從頭安裝（記憶/session 也會遺失）
hermes profile delete research-bot --yes
hermes profile install github.com/you/research-bot --alias

# 更新到最新的 main 但將 config.yaml 重置為 distribution 的預設值
hermes profile update research-bot --force-config --yes

Fork 並客製化

標準的 git 工作流程——distribution 本身就是 repo：

# 在 GitHub 上 fork repo，然後安裝你的 fork
hermes profile install github.com/yourname/forked-research-bot --alias

# 在 ~/.hermes/profiles/forked-research-bot/ 進行本地迭代
# 編輯 SOUL.md、commit、推送到你的 fork
# 上游變更：用一般方式 pull 到你的 fork

在推送前測試 distribution

在作者的機器上：

# 從本機目錄安裝（不需 git push）
hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test --alias

# 反覆調整、刪除、重新安裝直到滿意
hermes profile delete research-bot-test --yes
hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test

Distribution 中永遠不會包含的內容

即使作者不小心包含，安裝器也會強制排除以下路徑。沒有任何設定選項可以覆寫這個行為——這個安全機制是經過回歸測試的不變量：

auth.json——OAuth token、平台認證
.env——API 金鑰、機密
memories/——對話記憶
sessions/——對話紀錄
state.db、state.db-shm、state.db-wal——session 後設資料
logs/——agent 與錯誤日誌
workspace/——產生的工作檔案
plans/——暫存的計畫
home/——Docker 後端中的使用者 home 掛載點
*_cache/——圖片 / 音訊 / 文件快取
local/——使用者保留的客製化命名空間

當你 clone distribution 時，這些檔案根本不存在。當你更新時，它們保持不動。如果你在五台機器上安裝了同一份 distribution，你就有五套互不干擾的這份資料——每台機器一套。

安全性與信任

Profile distribution 預設是未簽署的。你必須信任：

Git 主機（GitHub / GitLab / 任何平台）提供作者推送的原始內容。
作者不會發佈惡意的 SOUL、技能或排程任務。

Distribution 中的排程任務不會自動排程——安裝器會印出 hermes -p <name> cron list，你需要明確啟用它們。SOUL.md 和技能在你開始與 profile 對話時就已啟用，所以如果你是從不認識的人那裡安裝，請在第一次執行前閱讀它們。

粗略的類比：安裝 distribution 就像安裝瀏覽器擴充功能或 VS Code 擴充功能。低門檻、高權限，信任來源。對於公司內部的 distribution，使用私有 repo 和你慣用的 git 認證——不需要額外設定。

未來版本可能會加入簽署、lockfile（.distribution-lock.yaml）搭配已解析的 commit SHA、以及 --dry-run 標記在套用更新前顯示 diff。這些目前都尚未發佈。

底層運作

關於實作細節、精確的 CLI 行為及所有參數，請參閱 Profile Commands 參考文件。

簡要說明：

install、update、info 都在 hermes profile 之下——不是平行的指令樹。
Manifest 格式是 YAML，只需極少的必要結構（僅 name）。
安裝器使用你本地的 git 進行 clone，所以你的 shell 已處理的任何認證（SSH 金鑰、credential helper）都能直接運作。
Clone 之後，.git/ 會被移除——已安裝的 profile 本身不是 git checkout，避免了「糟糕，我不小心把 .env 提交到 distribution 的 git 歷史中」的陷阱。
保留的 profile 名稱（hermes、test、tmp、root、sudo）在安裝時會被拒絕，以避免與常見的執行檔衝突。

另請參閱

Profiles：同時執行多個 Agent——基礎概念
Profile Commands 參考文件——每個參數、每個選項
hermes profile export / import——本地備份 / 還原（非 distribution）
在 Hermes 中使用 SOUL——撰寫人格
Personality 與 SOUL——SOUL 如何融入 agent
技能目錄——你可以打包的技能