hermes教程-配置文件分发：共享整个代理

配置文件分发：共享整个代理

配置文件分发将完整的 Hermes 代理（包括个性、技能、定时任务、MCP 连接、配置）打包成一个 git 仓库。任何有权访问该仓库的人都可以通过一条命令安装整个代理，原地更新，同时保留自己的记忆、会话和 API 密钥不变。

如果配置文件是一个本地代理，那么分发就是让这个代理变得可共享。

这意味着什么

在分发出现之前，共享一个 Hermes 代理意味着需要向他人发送：

你的 SOUL.md
要安装的技能列表
你的 config.yaml（不含密钥）
你连接了哪些 MCP 服务器的描述
你安排的任何定时任务
需要设置哪些环境变量的说明

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

有了分发，所有这些都存在于一个 git 仓库中：

text

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

接收者运行：

bash

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

……然后他们就拥有了完整的代理。他们填写自己的 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 存储的凭据——你的终端已经设置好的任何认证方式都能透明地工作。
可重现性就是一个提交 SHA。 与 pip 和 npm 记录的方式相同。

代价：接收者需要安装 git。在 2026 年任何运行 Hermes 的机器上，这已经是事实。

何时应该使用分发？

适合的场景：

你正在共享一个专门的代理——例如合规监控器、代码审查员、研究助手、客户支持机器人——与团队或社区共享。
你正在将同一个代理部署到多台机器，并且不想每次都手动复制文件。
你正在迭代一个代理，并希望接收者通过一条命令就能获取新版本。
你正在将代理作为产品构建——带有预设的默认值、精选的技能、调优的提示——供其他人作为起点使用。

不适合的场景：

你只是想在自己的机器上备份一个配置文件。 使用 hermes profile export / import —— 那是它们的用途。
你想在共享代理的同时共享 API 密钥。 auth.json 和 .env 被有意排除在分发之外。每个安装者自带凭据。
你想共享记忆/会话/对话历史。 那些是用户数据，不是分发内容。永远不包含。

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

以下是完整的端到端流程。选择你关心的那一方。

对于作者：发布分发

步骤 1 — 从一个可用的配置文件开始

像其他配置文件一样构建和完善代理：

bash

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：

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"
## 告诉安装者代理需要哪些环境变量。这些变量会与安装者的 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 仓库

bash

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 — 标记版本发布

每当代理达到一个稳定点，就更新版本并打标签：

bash

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

仓库的样子

一个完整的作者分发：

text

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/`	从不触及

你可以在清单中覆盖分发所有的列表：

yaml

distribution_owned:
  - SOUL.md
  - skills/research/            # 仅我的研究技能；其他已安装的技能保持不变
  - cron/digest.json

当省略时，应用上述默认值——这是大多数分发想要的。

对于安装者：使用分发

安装

bash

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

发生了什么：

将仓库克隆到临时目录。
读取 distribution.yaml，向你显示清单（名称、版本、描述、作者、所需环境变量）。
检查每个所需环境变量是否在你的 shell 环境和目标配置文件的现有 .env 中。标记为 ✓ 已设置 或 需要设置，这样你就知道需要配置什么。
请求确认。传递 -y / --yes 以跳过。
将分发所有的文件复制到 ~/.hermes/profiles/research-bot/（或清单中 name 解析到的位置）。
写入 .env.EXAMPLE，其中所需密钥被注释掉——复制到 .env 并填写。
使用 --alias，创建一个包装器，这样你可以直接运行 research-bot chat。

源类型

任何 git URL 都可以：

bash

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

覆盖配置文件名称

两个用户想要同一个分发但使用不同的配置文件名称：

bash

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

填写环境变量

安装后，代理的配置文件中包含一个 .env.EXAMPLE：

text

## 此 Hermes 分发所需的环境变量。
## 复制到 `.env` 并在运行前填写你自己的值。
## OpenAI API key (for model access)
## (required)
OPENAI_API_KEY=
## SerpAPI key for web search
## (optional)
## SERPAPI_KEY=

复制它：

bash

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

安装期间，已经在你的 shell 环境中设置好的所需密钥（例如在 ~/.zshrc 中导出的 OPENAI_API_KEY）会被标记为 ✓ 已设置——你不需要在 .env 中重复它们。

检查你安装了什么

bash

hermes profile info research-bot

显示：

text

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 列，这样你一眼就能看出哪些配置文件来自仓库，哪些是你手动构建的：

text

 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

更新

bash

hermes profile update research-bot

发生了什么：

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

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

删除

bash

hermes profile delete research-bot

删除提示会在要求你确认之前显示分发信息：

text

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:

这样你就不会在不知道代理来源或无法重新安装的情况下意外删除它。

用例和模式

个人：在多个机器间同步一个代理

你在笔记本电脑上构建了一个研究助手。你想在工作站上使用同一个代理。

bash

## 笔记本电脑
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 拉取到工作站。记忆按机器保留——笔记本电脑记住自己的对话，工作站记住自己的对话，它们不会冲突。

团队：发布一个经过审查的内部代理

你的工程团队想要一个共享的 PR 审查机器人，具有特定的 SOUL、特定的技能，以及一个定时任务，每次 PR 都通过它运行。

bash

## 工程主管
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，每个人在几分钟内就更新到新版本。

社区：发布一个公共代理

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

bash

## 你
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——与每个人都熟悉的 git 工作流相同。

产品：发布一个预设的代理

你构建了 Hermes 之上的东西——也许是合规监控框架、客户支持栈、特定领域的研究平台。你想将其作为产品分发。

yaml

## 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/）永远不会离开他们的机器。

临时：在共享基础设施上运行一次性脚本

你是运维负责人。你想要一个临时代理来诊断生产事故——一个预设的 SOUL，带有正确的工具和 MCP 连接——并在接下来的一周内在三个值班工程师的笔记本电脑上运行。

bash

## 你
## 构建配置文件，提交，推送到私有仓库
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 引用固定（#v1.2.0）已计划但不在初始版本中——安装目前跟踪默认分支。通过 hermes profile info <name> 跟踪你安装的版本，并在准备好之前暂缓更新。

检查你当前的版本与最新版本

bash

## 你安装的版本
hermes profile info research-bot | grep Version
## 最新的上游版本（无需安装）
git ls-remote --tags https://github.com/you/research-bot | tail -5

在更新中保留本地配置自定义

默认的更新行为已经做到了这一点：config.yaml 被保留。为了安全起见，将你的本地调整写入分发不拥有的文件：

yaml

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

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

强制干净重新安装

bash

## 彻底删除并重新安装（也会丢失记忆/会话）
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 工作流——分发只是仓库：

bash

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

在推送前测试分发

在作者的机器上：

bash

## 从本地目录安装（无需 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/ — 代理和错误日志
workspace/ — 生成的工作文件
plans/ — 草稿计划
home/ — Docker 后端中的用户主目录挂载
*_cache/ — 图像/音频/文档缓存
local/ — 用户保留的自定义命名空间

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

安全与信任

配置文件分发默认未签名。你信任：

git 托管方（GitHub / GitLab / 等）提供作者推送的字节。
作者不会发送恶意的 SOUL、技能或定时任务。

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

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

未来版本可能会添加签名、一个包含已解析提交 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）在安装时被拒绝，以避免与常见二进制文件冲突。

另请参阅

配置文件：运行多个代理 — 基本概念
配置文件命令参考 — 每个标志，每个选项
hermes profile export / import — 本地备份/恢复（非分发）
在 Hermes 中使用 SOUL — 编写个性
个性与 SOUL — SOUL 如何融入代理
技能目录 — 你可以捆绑的技能

字节笔记本

hermes教程-配置文件分发：共享整个代理

配置文件分发：共享整个代理

这意味着什么

为什么选择 git？

何时应该使用分发？

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

对于作者：发布分发

步骤 1 — 从一个可用的配置文件开始

步骤 2 — 添加 distribution.yaml

步骤 3 — 推送到 git 仓库

步骤 4 — 标记版本发布

仓库的样子

分发所有 vs 用户所有

对于安装者：使用分发

安装

源类型

覆盖配置文件名称

填写环境变量

检查你安装了什么

更新

删除

用例和模式

个人：在多个机器间同步一个代理

团队：发布一个经过审查的内部代理

社区：发布一个公共代理

产品：发布一个预设的代理

临时：在共享基础设施上运行一次性脚本

配方

固定到特定版本

检查你当前的版本与最新版本

在更新中保留本地配置自定义

强制干净重新安装

Fork 并自定义

在推送前测试分发

分发中永远不包含的内容

安全与信任

底层实现

另请参阅

步骤 2 — 添加 `distribution.yaml`