hermes-agent/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/profile-commands.md

sidebar_position
7

Profile 命令参考

本页涵盖所有与 Hermes profiles 相关的命令。通用 CLI 命令请参阅 CLI 命令参考。

hermes profile

hermes profile <subcommand>

管理 profile 的顶级命令。不带子命令运行 hermes profile 将显示帮助信息。

子命令	描述
list	列出所有 profile。
use	设置当前活跃（默认）profile。
create	创建新 profile。
delete	删除 profile。
show	显示 profile 详情。
alias	重新生成 profile 的 shell alias。
rename	重命名 profile。
export	将 profile 导出为 tar.gz 归档文件。
import	从 tar.gz 归档文件导入 profile。
install	从 git URL 或本地目录安装 profile 发行版。参见 Profile 发行版。
update	重新拉取发行版管理的 profile 并重新应用其 bundle。
info	显示 profile 的发行版元数据（来源 URL、commit、最后更新时间）。

hermes profile list

hermes profile list

列出所有 profile。当前活跃的 profile 以 * 标记。

示例：

$ hermes profile list
  default
* work
  dev
  personal

无选项。

hermes profile use

hermes profile use <name>

将 <name> 设为活跃 profile。此后所有 hermes 命令（不带 -p）都将使用该 profile。

参数	描述
<name>	要激活的 profile 名称。使用 default 可返回基础 profile。

示例：

hermes profile use work
hermes profile use default

hermes profile create

hermes profile create <name> [options]

创建新 profile。

参数 / 选项	描述
<name>	新 profile 的名称。必须是合法的目录名（字母数字、连字符、下划线）。
--clone	从当前 profile 复制 config.yaml、.env 和 SOUL.md。
--clone-all	从当前 profile 复制所有内容（config、memories、skills、sessions、state）。
--clone-from <profile>	从指定 profile 克隆，而非当前 profile。与 --clone 或 --clone-all 配合使用。
--no-alias	跳过 wrapper 脚本创建。
--description "<text>"	一到两句话描述该 profile 的用途。供 kanban 编排器根据角色而非仅凭 profile 名称来路由任务。可跳过，稍后通过 hermes profile describe 添加。持久化保存在 <profile_dir>/profile.yaml 中。
--no-skills	创建一个空 profile，不启用任何内置 skill。会在 profile 目录中写入 .no-skills 标记，使后续 hermes update 不再重新植入内置 skill 集，且拒绝与 --clone / --clone-all 组合使用（因为后者会复制 skill）。适用于不应继承完整 skill 目录的窄化编排器 profile 或沙箱 profile。

创建 profile 不会将该 profile 目录设为终端命令的默认项目/工作目录。如需让某个 profile 从特定项目目录启动，请在该 profile 的 config.yaml 中设置 terminal.cwd。

示例：

# 空白 profile — 需要完整配置
hermes profile create mybot

# 仅从当前 profile 克隆 config
hermes profile create work --clone

# 从当前 profile 克隆所有内容
hermes profile create backup --clone-all

# 从指定 profile 克隆 config
hermes profile create work2 --clone --clone-from work

hermes profile describe

hermes profile describe [<name>] [options]

读取或设置 profile 的描述。描述由 kanban 编排器使用，用于根据每个 profile 的能力路由任务，而非仅凭 profile 名称猜测。持久化保存在 <profile_dir>/profile.yaml 中，重启后仍有效，并与 gateway 共享。

不带任何标志时，打印当前描述（若为空则显示 (no description set for '<name>')）。

参数 / 选项	描述
<name>	要描述的 profile。除非使用 --all --auto，否则必填。
--text "<text>"	将描述设置为此精确文本（用户编写）。覆盖已有描述。
--auto	通过辅助 LLM 自动生成 1-2 句描述，依据为该 profile 已安装的 skill、配置的模型和名称。在 config.yaml 的 auxiliary.profile_describer 下配置模型。自动生成的描述会标记 description_auto: true，以便 dashboard 标记供审查。
--overwrite	与 --auto 配合使用时，也替换用户编写的描述（默认：跳过已明确设置描述的 profile）。
--all	与 --auto 配合使用时，扫描所有缺少描述的 profile。

示例：

# 读取当前描述
hermes profile describe researcher

# 显式设置描述
hermes profile describe researcher --text "Reads source code and writes findings."

# 让 LLM 生成描述
hermes profile describe researcher --auto

# 为所有没有描述的 profile 填充描述
hermes profile describe --all --auto

hermes profile delete

hermes profile delete <name> [options]

删除 profile 并移除其 shell alias。

参数 / 选项	描述
<name>	要删除的 profile。
--yes, -y	跳过确认提示。

示例：

hermes profile delete mybot
hermes profile delete mybot --yes

:::warning 此操作将永久删除 profile 的整个目录，包括所有 config、memories、sessions 和 skills。无法删除当前活跃的 profile。 :::

hermes profile show

hermes profile show <name>

显示 profile 的详细信息，包括其主目录、配置的模型、gateway 状态、skill 数量和配置文件状态。

此处显示的是 profile 的 Hermes 主目录，而非终端工作目录。终端命令从 terminal.cwd 启动（或在本地后端 cwd: "." 时从启动目录启动）。

参数	描述
<name>	要查看的 profile。

示例：

$ hermes profile show work
Profile: work
Path:    ~/.hermes/profiles/work
Model:   anthropic/claude-sonnet-4 (anthropic)
Gateway: stopped
Skills:  12
.env:    exists
SOUL.md: exists
Alias:   ~/.local/bin/work

hermes profile alias

hermes profile alias <name> [options]

重新生成位于 ~/.local/bin/<name> 的 shell alias 脚本。适用于 alias 被意外删除，或移动 Hermes 安装目录后需要更新的情况。

参数 / 选项	描述
<name>	要创建/更新 alias 的 profile。
--remove	移除 wrapper 脚本而非创建。
--name <alias>	自定义 alias 名称（默认：profile 名称）。

示例：

hermes profile alias work
# 创建/更新 ~/.local/bin/work

hermes profile alias work --name mywork
# 创建 ~/.local/bin/mywork

hermes profile alias work --remove
# 移除 wrapper 脚本

hermes profile rename

hermes profile rename <old-name> <new-name>

重命名 profile，同时更新目录和 shell alias。

参数	描述
<old-name>	当前 profile 名称。
<new-name>	新 profile 名称。

示例：

hermes profile rename mybot assistant
# ~/.hermes/profiles/mybot → ~/.hermes/profiles/assistant
# ~/.local/bin/mybot → ~/.local/bin/assistant

hermes profile export

hermes profile export <name> [options]

将 profile 导出为压缩的 tar.gz 归档文件。

参数 / 选项	描述
<name>	要导出的 profile。
-o, --output <path>	输出文件路径（默认：<name>.tar.gz）。

示例：

hermes profile export work
# 在当前目录创建 work.tar.gz

hermes profile export work -o ./work-2026-03-29.tar.gz

hermes profile import

hermes profile import <archive> [options]

从 tar.gz 归档文件导入 profile。

参数 / 选项	描述
<archive>	要导入的 tar.gz 归档文件路径。
--name <name>	导入后的 profile 名称（默认：从归档文件推断）。

示例：

hermes profile import ./work-2026-03-29.tar.gz
# 从归档文件推断 profile 名称

hermes profile import ./work-2026-03-29.tar.gz --name work-restored

发行版命令

:::tip 初次接触发行版？ 请先阅读 Profile 发行版用户指南 — 其中通过完整示例介绍了原因、时机和方法。以下章节是在你已知需求时使用的简明 CLI 参考。 :::

发行版将 profile 转变为可共享、有版本的制品，以 git 仓库形式发布。接收方只需一条命令即可安装发行版，并可在不影响本地 memories、sessions 或凭据的情况下就地更新。

auth.json 和 .env 永远不属于发行版的一部分 — 它们保留在安装用户的机器上。

接收方的用户数据（memories、sessions、auth、对 .env 的自有编辑）在初次安装和后续更新中始终得到保留。

:::info hermes profile export / import 仍是在本机进行 profile 本地备份和恢复的正确命令。发行版（install / update / info）是独立概念：通过 git 分发 profile，供他人安装。 :::

hermes profile install

hermes profile install <source> [--name <name>] [--alias] [--force] [--yes]

从 git URL 或本地目录安装 profile 发行版。

选项	描述
<source>	Git URL（github.com/user/repo、https://...、git@...、ssh://、git://）或包含 distribution.yaml 的本地目录根路径。
--name NAME	覆盖 manifest 中的 profile 名称。
--alias	同时创建 shell wrapper（例如 telemetry → hermes -p telemetry）。
--force	覆盖同名的已有 profile。用户数据仍会保留。
-y, --yes	跳过 manifest 预览确认提示。

安装程序会显示 manifest、列出所需的环境变量，并在询问确认前提示 cron 任务信息。所需环境变量会写入 .env.EXAMPLE 文件，复制为 .env 后填写即可。

示例：

# 从 GitHub 仓库安装（简写）
hermes profile install github.com/kyle/telemetry-distribution --alias

# 从完整 HTTPS git URL 安装
hermes profile install https://github.com/kyle/telemetry-distribution.git

# 从 SSH 安装
hermes profile install git@github.com:kyle/telemetry-distribution.git

# 开发时从本地目录安装
hermes profile install ./telemetry/

hermes profile update

hermes profile update <name> [--force-config] [--yes]

从记录的来源重新克隆发行版并应用更新。发行版所有的文件（SOUL.md、skills/、cron/、mcp.json）会被覆盖；用户数据（memories、sessions、auth、.env）不会被修改。

默认保留 config.yaml 以保持本地覆盖设置。传入 --force-config 可将其重置为发行版附带的 config。

hermes profile info

hermes profile info <name>

打印 profile 的发行版 manifest — 名称、版本、所需 Hermes 版本、作者、环境变量要求、来源 URL/路径，以及发行版最后一次 install 或 update 时记录的 Installed: 时间戳。适用于安装前检查共享 profile 的需求，以及发现"该 profile 已安装 6 个月未更新"等情况。

hermes profile list 也会在 Distribution 列中显示发行版名称和版本，hermes profile show <name> / delete <name> 会显示来源 URL，让你一眼看出哪些 profile 来自 git 仓库，哪些是本地创建的。

私有发行版

私有 git 仓库无需额外配置即可作为发行版来源 — 安装时会调用系统的 git 二进制文件，因此 shell 已配置的任何认证方式（SSH 密钥、git credential helper、GitHub CLI 存储的 HTTPS 凭据）均可透明生效。

# 使用 SSH 密钥，与普通 `git clone` 相同
hermes profile install git@github.com:your-org/internal-assistant.git

# 使用 git credential helper
hermes profile install https://github.com/your-org/internal-assistant.git

如果克隆时在终端交互式提示输入凭据，该提示会正常显示。请先按照对同一仓库执行 git clone 的方式配置好认证，再执行安装。

发行版 manifest（distribution.yaml）

每个发行版在其仓库根目录都有一个 distribution.yaml：

name: telemetry
version: 0.1.0
description: "Compliance monitoring harness"
hermes_requires: ">=0.12.0"
author: "Your Name"
license: "MIT"
env_requires:
  - name: OPENAI_API_KEY
    description: "OpenAI API key"
    required: true
  - name: GRAPHITI_MCP_URL
    description: "Memory graph URL"
    required: false
    default: "http://127.0.0.1:8000/sse"
distribution_owned:   # optional; defaults to SOUL.md, config.yaml,
                      #   mcp.json, skills/, cron/, distribution.yaml
  - SOUL.md
  - skills/compliance/
  - cron/

hermes_requires 支持 >=、<=、==、!=、>、<，或裸版本号（视为 >=）。若当前 Hermes 版本不满足规格，安装将失败并给出明确错误。

distribution_owned 为可选项。若设置，更新时仅替换这些路径；profile 中的其他内容保持用户所有。若省略，则应用上述默认值。

发布发行版

编写发行版就是一次 git push：

1. 在你的 profile 目录中创建 distribution.yaml，至少包含 name 和 version。
2. 初始化 git 仓库（或使用已有仓库），推送到 GitHub / GitLab / 任何 Hermes 可克隆的托管平台。
3. 告知接收方运行 hermes profile install <your-repo-url>。

使用 git tag 进行版本化发布 — 克隆 HEAD 的接收方将获得最新状态，你也可以随时在 manifest 中更新 version:。

hermes -p / hermes --profile

hermes -p <name> <command> [options]
hermes --profile <name> <command> [options]

全局标志，用于在不更改默认 profile 的情况下，在指定 profile 下运行任意 Hermes 命令。仅在该命令执行期间覆盖活跃 profile。

选项	描述
-p <name>, --profile <name>	本次命令使用的 profile。

示例：

hermes -p work chat -q "Check the server status"
hermes --profile dev gateway start
hermes -p personal skills list
hermes -p work config edit

hermes completion

hermes completion <shell>

生成 shell 补全脚本。包含对 profile 名称和 profile 子命令的补全。

参数	描述
<shell>	要生成补全脚本的 shell：bash、zsh 或 fish。

示例：

# 安装补全脚本
hermes completion bash >> ~/.bashrc
hermes completion zsh >> ~/.zshrc
hermes completion fish > ~/.config/fish/completions/hermes.fish

# 重新加载 shell
source ~/.bashrc

安装后，Tab 补全适用于：

• hermes profile <TAB> — 子命令（list、use、create 等）
• hermes profile use <TAB> — profile 名称
• hermes -p <TAB> — profile 名称

另请参阅

• Profiles 用户指南
• CLI 命令参考
• FAQ — Profiles 章节