配置文件分发：共享整个 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 并自定义​

在推送前测试分发版​

分发版中永远不包含的内容​

安全性与信任​

底层原理​

另见​