Profile 分发：分享完整 Agent

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

如果Profile 是一个本地 agent，那么分发就是使该 agent 可共享。

这意味着什么

在分发出现之前，分享一个 Hermes agent 意味着向某人发送：

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

……并希望他们正确组装。每次版本更新或错误修复都意味着重复这个交接过程。

使用分发后，所有这些内容都存在于一个 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。 不是重新下载整个归档。
透明。 用户可以浏览仓库、读取版本之间的 diff、针对它打开 issue、fork 它以进行自定义。
私有仓库免费使用。 SSH 密钥、git credential 助手、GitHub CLI 存储的凭据 — 你的终端已经设置的任何身份验证都会透明地应用。
可复现性是一个提交 SHA。 和 pip 与 npm 记录的一样。

权衡：接收者需要安装 git。在 2026 年任何运行 Hermes 的机器上，这都已经满足。

何时应该使用分发？

适合的场景：

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

不适合的场景：

你只是想在自己的机器上备份 profile。 使用 hermes profile export / import — 这就是它们的用途。
你想将 API 密钥与 agent 一起分享。 auth.json 和 .env 被故意排除在分发之外。每个安装者带来自己的凭据。
你想分享记忆 / 会话 / 对话历史。 那些是用户数据，不是分发内容。永远不应该随分发发送。

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

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

对于作者：发布分发

步骤 1 — 从一个可工作的 profile 开始

像任何其他 profile 一样构建和完善 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: "Autonomous research assistant with arXiv and web tools"
hermes_requires: ">=0.12.0"
author: "Your Name"
license: "MIT"

# 告诉安装者 agent 需要哪些环境变量。这些会针对安装
# 者的 shell 和目标 profile 的现有 .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 仓库

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 仓库包含 profile 目录中的所有内容，除了已经从分发中排除的内容：auth.json、.env、memories/、sessions/、state.db*、logs/、workspace/、*_cache/、local/。这些保留在你的机器上。如果你想要排除其他路径，也可以添加 .gitignore。

步骤 4 — 标记版本化发布

每次 agent 达到稳定点时， bump 版本并打标签：

# 编辑 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            # 必需
├── 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

发生了什么：

将仓库克隆到临时目录。
读取 distribution.yaml，向你显示清单（名称、版本、描述、作者、必需的环境变量）。
针对你的 shell 环境和目标 profile 的现有 .env 检查每个必需的环境变量。将每个标记为 ✓ 已设置 或 需要设置，这样你就确切知道要配置什么。
询问确认。传递 -y / --yes 以跳过。
将分发拥有的文件复制到 ~/.hermes/profiles/research-bot/（或清单的 name 解析到的任何位置）。
用必需密钥注释掉写入 .env.EXAMPLE — 复制到 .env 并填入。
使用 --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/

覆盖 profile 名称

两个用户想要不同 profile 名称下的同一个分发：

# 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 的 profile 包含一个 .env.EXAMPLE：

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

# 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）在安装期间标记为 ✓ 已设置 — 你不需要在 .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 来自仓库，哪些是你手建的：

 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、技能、定时任务、mcp.json）。
保留你的 config.yaml — 你可能调整了模型、温度或其他设置。传递 --force-config 以覆盖。
永远不触碰 用户数据：记忆、会话、身份验证、.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 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，每个人在几分钟内就使用新版本。

社区：发布公共 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 — 同样的每个人都已经知道的 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 — 一个带有正确工具和 MCP 连接的预制 SOUL — 并在接下来的一周运行在三名值班工程师的笔记本电脑上。

# 你
# 构建 profile、提交、推送到私有仓库
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）已计划但不在初始版本中 — 安装目前跟踪默认分支。通过 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

# 更新到当前 main 但将 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/ — 用户保留的自定义命名空间

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

安全和信任

Profile 分发默认是未签名的。你信任：

git 主机（GitHub / GitLab / 无论哪里）来提供作者推送的字节。
作者不会发送恶意的 SOUL、技能或定时任务。

来自分发的定时任务不会自动调度 — 安装者打印 hermes -p <name> cron list 并且你显式启用它们。SOUL.md 和技能在你开始与 profile 聊天时就会激活，所以如果你从你不认识的人那里安装，在首次运行前先阅读它们。

粗略类比：安装分发就像安装浏览器扩展或 VS Code 扩展。低阻力、高权力、信任来源。对于公司内部分发，使用私有仓库和你正常的 git 身份验证 — 没有新内容需要配置。

未来版本可能会添加签名、带有已解析提交 SHA 的锁文件（.distribution-lock.yaml）和在应用更新之前打印 diff 的 --dry-run 标志。这些都没有发布。

底层实现

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

简短版本：

install、update、info 位于 hermes profile 内部 — 不是并行命令树。
清单格式是带有微小必需模式（仅 name）的 YAML。
安装者使用你本地的 git 二进制文件进行克隆，所以你的 shell 已经处理的任何身份验证（SSH 密钥、凭据助手）都会透明地工作。
克隆后，.git/ 被剥离 — 安装的 profile 本身不是 git 检出，避免了"哦我的，我不小心将我的 .env 提交到分发的 git 历史"陷阱。
保留的 profile 名称（hermes、test、tmp、root、sudo）在安装时被拒绝，以避免与常见二进制文件冲突。

另请参阅

Profiles：运行多个 Agents — 基础概念
Profile 命令参考 — 每个标志、每个选项
hermes profile export / import — 本地备份 / 恢复（不是分发）
在 Hermes 中使用 SOUL — 创作个性
个性 & SOUL — SOUL 如何适应 agent
技能目录 — 你可以捆绑的技能

这意味着什么​

为什么选择 git？​

何时应该使用分发？​

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

对于作者：发布分发​

步骤 1 — 从一个可工作的 profile 开始​

步骤 2 — 添加 distribution.yaml​

步骤 3 — 推送到 git 仓库​

步骤 4 — 标记版本化发布​

仓库看起来像什么​

分发拥有 vs 用户拥有​

对于安装者：使用分发​

安装​

源类型​

覆盖 profile 名称​

填入环境变量​

检查你安装了什么​

更新​

删除​

使用场景和模式​

个人：跨机器同步一个 agent​

团队：发布经过审查的内部 agent​

社区：发布公共 agent​

产品：发布一个有主见的 agent​

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

技巧​

固定到特定版本​

检查你所在的版本 vs 最新版本​

在更新期间保留本地配置自定义​

强制全新安装​

Fork 和自定义​

在推送前测试分发​

分发中永远不包含什么​

安全和信任​

底层实现​

另请参阅​