profile-distributions

配置集分发（Profile Distributions）：分享完整 Agent

配置集分发（profile distribution） 将完整的 Hermes agent（包括人格、技能、定时任务、MCP 连接、配置）打包为一个 git 仓库。任何拥有该仓库访问权限的人都可以通过一条命令安装整个 agent，就地更新，并且保留自己的记忆、会话和 API 密钥不变。

如果说配置集（profile）是一个本地的 agent，那么分发就是将这个 agent 变得可分享。

这是什么意思

在分发功能出现之前，分享一个 Hermes agent 意味着需要向对方发送：

1. 你的 SOUL.md
2. 一份要安装的技能列表
3. 你的 config.yaml（去掉密钥部分）
4. 关于你配置了哪些 MCP 服务器的说明
5. 你安排的定时任务
6. 需要设置哪些环境变量的说明

……然后希望他们能正确组装。每次版本更新或 bug 修复都需要重复这一过程。

有了分发功能，以上所有内容都放在一个 git 仓库中：

my-research-agent/
├── distribution.yaml    # 清单：名称、版本、环境变量要求
├── SOUL.md              # agent 的人格/系统提示词
├── config.yaml          # 模型、温度、推理、工具默认配置
├── skills/              # 随 agent 附带的技能
├── cron/                # agent 运行的定时任务
└── mcp.json             # agent 连接的 MCP 服务器

接收者运行：

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 被有意排除在分发之外。每个安装者自带凭据。
• 你想分享记忆/会话/对话历史。 那些是用户数据，不是分发内容。绝不会被分发。

生命周期：从作者到安装者再到更新

以下是完整的端到端流程。选择你关心的角色。

---

面向作者：发布一个分发

第 1 步——从一个可用的配置集开始

像其他配置集一样构建和完善 agent：

hermes profile create research-bot
research-bot setup                    # 配置模型、API 密钥
# 编辑 ~/.hermes/profiles/research-bot/SOUL.md
# 安装技能、配置 MCP 服务器、安排定时任务等
research-bot chat                     # 自己先用起来，直到感觉合适

第 2 步——添加 distribution.yaml

在 ~/.hermes/profiles/research-bot/distribution.yaml 中创建：

name: research-bot
version: 1.0.0
description: "具有 arXiv 和网络工具的自主研究助手"
hermes_requires: ">=0.12.0"
author: "Your Name"
license: "MIT"
 
# 告诉安装者该 agent 需要哪些环境变量。这些变量会与
# 安装者的 shell 和已有的 .env 文件进行比对，以免他们
# 对已配置的密钥反复被询问。
env_requires:
  - name: OPENAI_API_KEY
    description: "OpenAI API 密钥（用于模型访问）"
    required: true
  - name: SERPAPI_KEY
    description: "SerpAPI 密钥（用于网络搜索）"
    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

该仓库现在就是一个分发了。任何有访问权限的人都可以安装它。

:::note git 仓库包含 配置集目录中除了已被分发排除的所有内容：auth.json、.env、memories/、sessions/、state.db*、logs/、workspace/、*_cache/、local/。这些文件保留在你的机器上。你也可以添加 .gitignore 来排除其他路径。 :::

第 4 步——标记版本化发布

每次 agent 达到一个稳定点，更新版本并打标签：

# 编辑 distribution.yaml：version: 1.1.0
git add distribution.yaml SOUL.md skills/
git commit -m "v1.1.0：更精确的研究 SOUL，添加 arxiv 技能"
git tag v1.1.0
git push --tags

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

仓库的目录结构

一个完整的已发布分发：

research-bot/
├── distribution.yaml            # 必需
├── SOUL.md                      # 强烈推荐
├── config.yaml                  # 模型、提供商、工具默认配置
├── mcp.json                     # MCP 服务器连接
├── skills/
│   ├── arxiv-search/SKILL.md
│   ├── paper-summarization/SKILL.md
│   └── citation-lookup/SKILL.md
├── cron/
│   └── weekly-digest.json       # 定时任务
└── README.md                    # 面向人类的描述（可选）

分发所有 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/            # 仅我的研究技能；其他已安装的技能保留
  - cron/digest.json

省略时，应用上述默认规则——这也是大多数分发所期望的行为。

---

面向安装者：使用一个分发

安装

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

执行过程：

1. 将仓库克隆到临时目录。
2. 读取 distribution.yaml，向你展示清单（名称、版本、描述、作者、所需环境变量）。
3. 检查每个必需的环境变量是否存在于你的 shell 环境和目标配置集的已有 .env 中。标记每个变量为 ✓ 已设置 或 需要设置，以便你确切知道要配置什么。
4. 请求确认。传递 -y / --yes 可跳过。
5. 将分发所有的文件复制到 ~/.hermes/profiles/research-bot/（或清单中 name 解析到的路径）。
6. 写入包含必需密钥注释的 .env.EXAMPLE——复制到 .env 并填入值。
7. 使用 --alias，创建一个包装器，以便你可以直接运行 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 认证访问私有仓库
hermes profile install git@github.com:your-org/internal-bot.git
 
# 开发期间的本地目录（无需 git push）
hermes profile install ~/my-profile-in-progress/

覆盖配置集名称

两个用户希望以不同的配置集名称使用同一个分发：

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

填写环境变量

安装后，agent 的配置集中包含一个 .env.EXAMPLE：

# 此 Hermes 分发所需的环境变量。
# 复制到 `.env` 并填入你自己的值后再运行。

# OpenAI API 密钥（用于模型访问）
# （必需）
OPENAI_API_KEY=

# 用于网络搜索的 SerpAPI 密钥
# （可选）
# SERPAPI_KEY=

复制它：

cp ~/.hermes/profiles/research-bot/.env.EXAMPLE ~/.hermes/profiles/research-bot/.env
# 编辑 .env，粘贴你的真实密钥

已经存在于你 shell 环境中的必需密钥（例如在 ~/.zshrc 中导出的 OPENAI_API_KEY）在安装时会被标记为 ✓ 已设置——你无需在 .env 中重复添加。

检查你安装了什么

hermes profile info research-bot

显示：

Distribution: research-bot
Version:      1.0.0
Description:  具有 arXiv 和网络工具的自主研究助手
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 密钥（用于模型访问）
  SERPAPI_KEY (optional) — SerpAPI 密钥（用于网络搜索）

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

执行过程：

1. 从记录的来源 URL 重新克隆仓库。
2. 替换分发所有的文件（SOUL、技能、cron、mcp.json）。
3. 保留你的 config.yaml——你可能已调整了模型、温度或其他设置。传递 --force-config 可覆盖。
4. 永不触及用户数据：记忆、会话、认证、.env、日志、状态。

无需重新下载整个归档文件。不会覆盖你对配置的本地修改。不会删除你的对话历史。

移除

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:

这样你永远不会在不知道 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 审查器"
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，每个人都能在几分钟内用上新版本。

社区使用：发布一个公开 agent

你构建了一些新颖的东西——比如一个”Polymarket 交易助手”或”学术论文摘要器”或”Minecraft 服务器运维助手”。你想分享它。

# 你
cd ~/.hermes/profiles/polymarket-trader
# 在仓库根目录写一个扎实的 README.md——GitHub 会在仓库页面显示它
git init && git add . && git commit -m "v1.0"
git tag v1.0.0
# 发布到公开的 GitHub 仓库
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-on-top——可能是一个合规监控工具、一个客服系统、一个特定领域的研究平台。你想把它作为产品分发。

# distribution.yaml
name: telemetry-harness
version: 2.3.1
description: "合规遥测工具——监控和审查受监管的工作流"
hermes_requires: ">=0.13.0"
author: "Acme Compliance Inc."
license: "Commercial"
 
env_requires:
  - name: ACME_API_KEY
    description: "你的 Acme Compliance 许可证密钥（联系 support@acme.com）"
    required: true
  - name: OPENAI_API_KEY
    description: "用于模型访问的 OpenAI API 密钥"
    required: true
  - name: GRAPHITI_MCP_URL
    description: "你的 Graphiti 知识图谱实例的 URL"
    required: false
    default: "http://127.0.0.1:8000/sse"

你的客户通过一条命令安装；安装预览精确告诉他们需要准备好哪些密钥；你打标签发布新版本时更新立即生效；他们的合规数据（memories/、sessions/）永远不会离开他们的机器。

临时使用：共享基础设施上的一次性脚本

你是运维负责人。你想要一个临时 agent 来诊断生产事故——一个包含正确工具和 MCP 连接的预制 SOUL——在未来一周内运行在三名值班工程师的笔记本上。

# 你
# 构建配置集，提交，推送到私有仓库
git push -u origin main
 
# 每位值班工程师
hermes profile install git@github.com:your-org/incident-2026-q2.git --alias
 
# 事故解决——拆除
hermes profile delete incident-2026-q2

安装-删除循环足够轻量，可以视为一次性使用。

---

技巧

锁定到特定版本

:::note Git 引用锁定（#v1.2.0）已计划但尚未在初始版本中提供——安装目前跟踪默认分支。通过 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 被保留。为了安全起见，将你的本地调整写到一个分发不拥有的文件中：

# ~/.hermes/profiles/research-bot/local/my-overrides.yaml
# （分发永不触及 local/）

……并根据需要从 config.yaml 或你的 SOUL 中引用它。

强制全新安装

# 彻底删除并全新安装（也会丢失记忆/会话）
hermes profile delete research-bot --yes
hermes profile install github.com/you/research-bot --alias
 
# 更新到当前主分支，但将 config.yaml 重置为分发的默认值
hermes profile update research-bot --force-config --yes

Fork 并定制

标准的 git 工作流——分发只是仓库：

# 在 GitHub 上 fork 仓库，然后安装你的 fork
hermes profile install github.com/yourname/forked-research-bot --alias
 
# 在 ~/.hermes/profiles/forked-research-bot/ 中本地迭代
# 编辑 SOUL.md，提交，推送到你的 fork
# 上游变更：以常规方式拉取到你的 fork

在推送前测试分发

在作者的机器上：

# 从本地目录安装（无需 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

---

分发中绝不包含的内容（绝不）

安装程序硬性排除以下路径，即使作者意外将它们纳入。没有配置选项可以覆盖这一点——这个安全防护是一个经过回归测试的不变规则：

• auth.json——OAuth 令牌、平台凭据
• .env——API 密钥、密钥
• memories/——对话记忆
• sessions/——对话历史
• state.db、state.db-shm、state.db-wal——会话元数据
• logs/——agent 和错误日志
• workspace/——生成的工作文件
• plans/——草稿计划
• home/——Docker 后端中的用户 home 挂载点
• *_cache/——图片/音频/文档缓存
• local/——用户保留的定制命名空间

当你克隆一个分发时，这些内容就是不存在。当你更新时，它们保持不变。如果你在五台机器上安装了同一个分发，你拥有五套相互隔离的这些数据——每台机器一套。

安全与信任

配置集分发默认是无签名的。你信任的是：

• git 托管平台（GitHub / GitLab / 其他）提供作者推送的内容。
• 作者不会发布恶意的 SOUL、技能或定时任务。

分发中的定时任务不会自动安排——安装程序会打印 hermes -p <name> cron list，你需要显式启用它们。SOUL.md 和技能在你开始与配置集对话后立即生效，所以如果你从陌生人那里安装，在首次运行前请先阅读它们。

粗略类比：安装分发就像安装浏览器扩展或 VS Code 扩展。低摩擦、高能力、信任来源。对于公司内部分发，使用私有仓库和正常的 git 认证——无需额外配置。

未来版本可能会添加签名、包含已解析 commit SHA 的锁文件（.distribution-lock.yaml）以及在应用更新前打印差异的 --dry-run 标志。这些功能目前尚未发布。

底层实现

有关实现细节、精确的 CLI 行为和所有标志，请参阅配置集命令参考。

简要说明：

• install、update、info 位于 hermes profile 下——而非独立的命令树。
• 清单格式为 YAML，具有最小的必需模式（仅 name）。
• 安装程序使用你本地的 git 二进制进行克隆，因此你的 shell 已处理的任何认证（SSH 密钥、凭据辅助工具）都能透明工作。
• 克隆后，.git/ 被剥离——已安装的配置集本身不是一个 git 检出，避免了”哦天哪，我不小心将我的 .env 提交到了分发的 git 历史中”这类陷阱。
• 保留的配置集名称（hermes、test、tmp、root、sudo）在安装时被拒绝，以避免与常见二进制文件冲突。

参见

• 配置集（Profiles）：运行多个 Agent——基础概念
• 配置集命令参考——每个标志、每个选项
• hermes profile export / import——本地备份/恢复（非分发）
• 使用 SOUL 与 Hermes——编写人格
• 人格与 SOUL——SOUL 如何融入 agent
• 技能目录——你可以打包的技能