配置文件分發：共享整個 Agent

配置文件分發（profile distribution） 將完整的 Hermes agent —— 包括人格設定、技能、定時任務、MCP 連接、配置 —— 打包為一個 git 倉庫。任何有權訪問該倉庫的人都可以通過一條命令安裝整個 agent，就地更新，並保持其自身的記憶、會話和 API 密鑰不受影響。

如果配置文件（profile）是本地 agent，那麼分發版（distribution）就是使其可共享的 agent。

這意味著什麼

在引入分發版之前，共享 Hermes agent 意味著向某人發送：

你的 SOUL.md
要安裝的技能列表
你的 config.yaml（去除敏感信息）
你連接的 MCP 服務器描述
你安排的任何定時任務
需要設置哪些環境變量的說明

……並希望他們能正確組裝。每次版本升級或錯誤修復都意味著重複這一交接過程。

使用分發版後，所有這些都存在於一個 git 倉庫中：

my-research-agent/
├── distribution.yaml    # manifest: name, version, env-var requirements
├── SOUL.md              # the agent's personality / system prompt
├── config.yaml          # model, temperature, reasoning, tool defaults
├── skills/              # bundled skills that come with the agent
├── cron/                # scheduled tasks the agent runs
└── mcp.json             # MCP servers the agent connects to

接收者運行：

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

……現在他們就擁有了整個 agent。他們填入自己的 API 密鑰（.env.EXAMPLE → .env），然後可以運行 my-research-agent chat 或通過 Telegram / Discord / Slack / 任何網關平臺與之交互。當你推送新版本時，他們運行 hermes profile update my-research-agent 並拉取你的更改 —— 他們的記憶和會話保持不變。

為什麼選擇 git？

我們考慮過 tarball、HTTP 歸檔文件、自定義格式。但沒有一種比得上 git：

作者無需構建步驟。 推送到 GitHub；用戶安裝。沒有“打包這個，上傳那個，更新索引”的循環。
標籤、分支和提交本身就是版本控制系統。 推送標籤為我們完成了其他工具中“打包 + 上傳發布版”所做的工作。
更新只是 fetch 操作。 而不是重新下載整個歸檔文件。
透明。 用戶可以瀏覽倉庫，閱讀版本間的差異，針對它開啟 issue，或者 fork 它以進行自定義。
私有倉庫免費可用。 SSH 密鑰、git credential 助手、GitHub CLI 存儲的憑據 —— 無論你的終端已配置何種身份驗證方式，均可透明應用。
可復現性由 commit SHA 保證。 這與 pip 和 npm 記錄的方式相同。

權衡之處：接收者需要安裝 git。在 2026 年運行 Hermes 的任何機器上，這已經是既定事實。

何時應該使用分發版？

適用場景：

你正在共享一個專用 agent —— 如合規監控器、代碼審查員、研究助手、客戶支持機器人 —— 給團隊或社區使用。
你正在將同一個 agent 部署到多臺機器，且不想每次都手動複製文件。
你正在迭代開發一個 agent，並希望接收者通過一條命令獲取新版本。
你將 agent 作為產品構建 —— 包含固執己見的默認值、精選技能、調優後的提示詞 —— 供其他人用作起點。

不適用場景：

你只想在本地機器上備份配置文件。 請使用 hermes profile export / import —— 這些命令正是為此而設。
你希望隨 agent 一起共享 API 密鑰。 auth.json 和 .env 被故意排除在分發版之外。每個安裝者都需自帶憑據。
你希望共享記憶 / 會話 / 對話歷史。 這些屬於用戶數據，而非分發內容。絕不會隨分發版 shipped。

生命週期：從作者到安裝者再到更新

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

對於作者：發佈分發版

步驟 1 — 從可用的配置文件開始

像構建其他配置文件一樣構建和完善 agent：

hermes profile create research-bot
research-bot setup                    # configure model, API keys
# Edit ~/.hermes/profiles/research-bot/SOUL.md
# Install skills, wire up MCP servers, schedule cron jobs, etc.
research-bot chat                     # dogfood until it feels right

步驟 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"

# Tell installers which env vars the agent needs. These are checked against
# the installer's shell and existing .env file so they don't get nagged
# about keys they already have configured.
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 倉庫

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

該倉庫現在就是一個分發版。任何有權訪問的人都可以安裝它。

備註

git 倉庫包含配置文件目錄中的所有內容，除了那些已被排除在分發版之外的內容：auth.json、.env、memories/、sessions/、state.db*、logs/、workspace/、*_cache/、local/。這些保留在你的機器上。如果你希望排除其他路徑，也可以添加 .gitignore。

步驟 4 — 標記版本化發佈

每次 agent 達到穩定狀態時，提升版本號並打標籤：

# Edit 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 的接收者將拉取最新版本。

倉庫結構示例

一個完整的已創作分發版：

research-bot/
├── distribution.yaml            # required
├── SOUL.md                      # strongly recommended
├── config.yaml                  # model, provider, tool defaults
├── mcp.json                     # MCP server connections
├── skills/
│   ├── arxiv-search/SKILL.md
│   ├── paper-summarization/SKILL.md
│   └── citation-lookup/SKILL.md
├── cron/
│   └── weekly-digest.json       # scheduled tasks
└── README.md                    # human-facing description (optional)

分發版所屬 vs 用戶所屬

當安裝者更新到新版本時，某些內容會被替換（作者域），而某些內容保持不變（安裝者域）。默認情況如下：

類別	路徑	更新時行為
發行版所有	`SOUL.md`, `config.yaml`, `mcp.json`, `skills/`, `cron/`, `distribution.yaml`	從新克隆中替換
配置覆蓋	`config.yaml`	默認情況下實際保留 —— 安裝程序可能已調整模型或提供商。更新時傳遞 `--force-config` 以重置。
用戶所有	`memories/`, `sessions/`, `state.db`, `auth.json`, `.env`, `logs/`, `workspace/`, `plans/`, `home/`, `_cache/`, `local/`	永不觸碰

你可以在清單中覆蓋發行版所有的文件列表：

distribution_owned:
  - SOUL.md
  - skills/research/            # only my research skills; other installed skills stay
  - cron/digest.json

省略時，將應用上述默認值 —— 這也是大多數發行版所期望的。

致安裝者：使用發行版

安裝

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

發生的情況：

將倉庫克隆到臨時目錄。
讀取 distribution.yaml，向你顯示清單（名稱、版本、描述、作者、所需的環境變量）。
根據你的 shell 環境和目標配置文件現有的 .env 檢查每個所需的環境變量。將每個標記為 ✓ set（已設置）或 needs setting（需要設置），以便你確切知道需要配置什麼。
請求確認。傳遞 -y / --yes 以跳過。
將發行版所有的文件複製到 ~/.hermes/profiles/research-bot/（或清單中 name 解析到的任何位置）。
寫入 .env.EXAMPLE，其中所需的鍵已被註釋掉 —— 將其複製為 .env 並填寫。
使用 --alias 時，創建一個包裝器，以便你可以直接運行 research-bot chat。

源類型

任何 git URL 均可工作：

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

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

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

# Self-hosted, GitLab, Gitea, Forgejo — any Git host
hermes profile install https://git.example.com/team/research-bot.git

# Private repo using your configured git auth
hermes profile install git@github.com:your-org/internal-bot.git

# Local directory during development (no git push needed)
hermes profile install ~/my-profile-in-progress/

覆蓋配置文件名稱

兩個用戶希望在不同的配置文件名稱下使用相同的發行版：

# Alice
hermes profile install github.com/acme/support-bot --name support-us --alias
# Bob (same distribution, different local name)
hermes profile install github.com/acme/support-bot --name support-eu --alias

填寫環境變量

安裝後，代理的配置文件中包含一個 .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
# Edit .env, paste your real keys

在安裝過程中，那些已經存在於你的 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          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 重新克隆倉庫。
替換髮行版所有的文件（SOUL、skills、cron、mcp.json）。
保留你的 config.yaml —— 你可能已調整了模型、溫度或其他設置。傳遞 --force-config 以覆蓋。
永不觸碰 用戶數據：memories、sessions、auth、.env、logs、state。

不會重新下載整個歸檔文件。不會覆蓋你對配置的本地更改。不會刪除你的對話歷史。

移除

hermes profile delete research-bot

刪除提示會在要求你確認之前顯示發行版信息：

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:

因此，你永遠不會在不知道其來源或無法重新安裝的情況下意外刪除代理。

用例和模式

個人：在多臺機器間同步一個代理

你在筆記本電腦上構建了一個研究助手。你希望在工作站上擁有相同的代理。

# Laptop
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

# Workstation
hermes profile install github.com/you/research-bot --alias
# Fill in .env. Done.

筆記本電腦上的任何迭代（git commit && push）都會通過 hermes profile update research-bot 拉取到工作站。記憶保持每臺機器獨立 —— 筆記本電腦記住它自己的對話，工作站記住它自己的，它們不會衝突。

團隊：發佈經過審查的內部代理

你的工程團隊希望擁有一個共享的 PR 審查機器人，具有特定的 SOUL、特定的技能，以及一個對每個 PR 運行該機器人的 cron 任務。

# Engineering lead
cd ~/.hermes/profiles/pr-reviewer
# ... build and tune ...
git init && git add . && git commit -m "v1.0 PR reviewer"
git tag v1.0.0
git push -u origin main --tags    # push to your company's internal Git host

# Each engineer
hermes profile install git@github.com:your-org/pr-reviewer.git --alias
# Fill in .env with their own API key (billed to them), .env.EXAMPLE points at what's required
pr-reviewer chat

當負責人發佈 v1.1（更好的 SOUL，新技能）時，工程師運行 hermes profile update pr-reviewer，每個人都在幾分鐘內更新到新版本。

社區：發佈公共代理

你構建了一些新穎的東西 —— 也許是一個“Polymarket 交易員”、“學術論文摘要器”或“Minecraft 服務器運維助手”。你想分享它。

# You
cd ~/.hermes/profiles/polymarket-trader
# Write a solid README.md at the repo root — GitHub shows it on the repo page
git init && git add . && git commit -m "v1.0"
git tag v1.0.0
# Publish to a public GitHub repo
git remote add origin https://github.com/you/hermes-polymarket-trader.git
git push -u origin main --tags

# Anyone
hermes profile install github.com/you/hermes-polymarket-trader --alias

推文發送安裝命令。嘗試它的人會向你發送 issue 和 PR。如果有人想要自定義，他們可以進行 fork —— 這是每個人都熟悉的相同 git 工作流。

產品：發佈有觀點的代理

你構建了基於 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/）永遠不會離開他們的機器。

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

你是運維負責人。你想要一個臨時代理來診斷生產事件 —— 一個帶有正確工具和 MCP 連接的預製 SOUL —— 並在接下來的一週內在三位待命工程師的筆記本電腦上運行。

# You
# Build the profile, commit, push a private repo
git push -u origin main

# Each on-call
hermes profile install git@github.com:your-org/incident-2026-q2.git --alias

# Incident resolved — tear it down
hermes profile delete incident-2026-q2

安裝-刪除循環足夠廉價，可以一次性使用。

配方

鎖定到特定版本

備註

Git 引用鎖定（#v1.2.0）已在計劃中，但尚未包含在初始版本中——目前安裝會跟蹤默認分支。請通過 hermes profile info <name> 跟蹤已安裝的版本，並在準備好之前暫緩更新。

檢查當前版本與最新版本

# Your installed version
hermes profile info research-bot | grep Version

# Latest upstream (without installing)
git ls-remote --tags https://github.com/you/research-bot | tail -5

在更新期間保留本地配置自定義

默認的更新行為已經實現了這一點：config.yaml 會被保留。為了安全起見，請將你的本地調整寫入分發版不擁有的文件中：

# ~/.hermes/profiles/research-bot/local/my-overrides.yaml
# (distribution never touches local/)

……並根據需要從 config.yaml 或你的 SOUL 中引用它。

強制乾淨重新安裝

# Nuke and re-install from scratch (loses memories/sessions too)
hermes profile delete research-bot --yes
hermes profile install github.com/you/research-bot --alias

# Update to current main but reset config.yaml to the distribution's default
hermes profile update research-bot --force-config --yes

Fork 並自定義

標準的 git 工作流——分發版只是代碼倉庫：

# Fork the repo on GitHub, then install your fork
hermes profile install github.com/yourname/forked-research-bot --alias

# Iterate locally in ~/.hermes/profiles/forked-research-bot/
# Edit SOUL.md, commit, push to your fork
# Upstream changes: pull them into your fork the usual way

在推送前測試分發版

在作者的機器上：

# Install from a local directory (no git push needed)
hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test --alias

# Tweak, delete, re-install until it's right
hermes profile delete research-bot-test --yes
hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test

分發版中永遠不包含的內容

即使作者意外打包了這些路徑，安裝程序也會強制排除它們。沒有任何配置選項允許你覆蓋此行為——這一安全防護是一個經過迴歸測試的不變量：

auth.json — OAuth 令牌、平臺憑證
.env — API 密鑰、機密信息
memories/ — 對話記憶
sessions/ — 對話歷史
state.db, state.db-shm, state.db-wal — 會話元數據
logs/ — agent 和錯誤日誌
workspace/ — 生成的工作文件
plans/ — 臨時計劃
home/ — Docker 後端中用戶的 home 掛載點
*_cache/ — 圖像/音頻/文檔緩存
local/ — 用戶保留的自定義命名空間

當你克隆一個分發版時，這些文件根本不存在。當你更新時，它們會保持原位。如果你在五臺機器上安裝了相同的分發版，你將擁有五組隔離的數據——每臺機器一組。

安全性與信任

Profile 分發版默認未簽名。你需要信任：

Git 託管平臺（GitHub / GitLab / 其他平臺）提供作者推送的文件字節。
作者不會打包惡意的 SOUL、技能或 cron 任務。

來自分發版的 cron 任務不會自動調度——安裝程序會打印 hermes -p <name> cron list，你需要顯式啟用它們。SOUL.md 和技能在你開始與 profile 聊天后立即生效，因此如果你是從不認識的人那裡安裝，請在首次運行前閱讀它們。

粗略類比：安裝分發版類似於安裝瀏覽器擴展或 VS Code 擴展。低摩擦、高能力、信任來源。對於公司內部的分發版，使用私有倉庫和你常規的 git 認證即可——無需配置新內容。

未來版本可能會添加簽名、包含已解析 commit SHA 的鎖文件（.distribution-lock.yaml），以及在應用更新前打印差異的 --dry-run 標誌。這些功能目前尚未發佈。

底層原理

有關實現細節、精確的 CLI 行為和所有標誌，請參閱 Profile 命令參考。

簡而言之：

install、update、info 位於 hermes profile 內部——而不是平行的命令樹。
清單格式為 YAML，具有最小的必需架構（僅 name）。
安裝程序使用本地的 git 二進制文件進行克隆，因此你的 shell 已經處理的任何認證（SSH 密鑰、憑證助手）都能透明地工作。
克隆後，.git/ 會被剝離——安裝的 profile 本身不是 git 檢出，從而避免“哎呀，我不小心將 .env 提交到了分發版的 git 歷史記錄中”這類陷阱。
保留的 profile 名稱（hermes、test、tmp、root、sudo）在安裝時會被拒絕，以避免與常見二進制文件發生衝突。

另見

Profiles：運行多個 Agent — 基本概念
Profile 命令參考 — 每個標誌、每個選項
hermes profile export / import — 本地備份/恢復（非分發版）
在 Hermes 中使用 SOUL — 編寫人格
人格與 SOUL — SOUL 如何融入 agent
技能目錄 — 你可以捆綁的技能

這意味著什麼​

為什麼選擇 git？​

何時應該使用分發版？​

生命週期：從作者到安裝者再到更新​

對於作者：發佈分發版​

步驟 1 — 從可用的配置文件開始​

步驟 2 — 添加 distribution.yaml​

步驟 3 — 推送到 git 倉庫​

步驟 4 — 標記版本化發佈​

倉庫結構示例​

分發版所屬 vs 用戶所屬​

致安裝者：使用發行版​

安裝​

源類型​

覆蓋配置文件名稱​

填寫環境變量​

檢查已安裝的內容​

更新​

移除​

用例和模式​

個人：在多臺機器間同步一個代理​

團隊：發佈經過審查的內部代理​

社區：發佈公共代理​

產品：發佈有觀點的代理​

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

配方​

鎖定到特定版本​

檢查當前版本與最新版本​

在更新期間保留本地配置自定義​

強制乾淨重新安裝​

Fork 並自定義​

在推送前測試分發版​

分發版中永遠不包含的內容​

安全性與信任​

底層原理​

另見​