Hermes Launchpad

@bitseek/hermes-launchpad 是一个独立于 Hermes Agent 主仓库的 npx 安装、导入、更新、诊断和导出工具。它的目标是让企业用户用一条命令安装官方 Hermes，并把已经训练好的 Hermes profile 包导入本机。

这个仓库不修改 Hermes Agent 核心代码。Launchpad 只调用公开的 Hermes CLI 命令，并读写 Hermes 已有的 profile 目录结构。

Workspace 约定

当前 ~/hermes workspace 里有两个核心 npm 包职责：

• hermes-agent-pack/ 发布 @bitseek/hermes-launchpad，负责安装 Hermes Agent、 导入 profile pack、写入模型配置和密钥、并编排 WebUI。
• @bitseek/hermes-webui 是专门打包和启动 WebUI 的 wrapper 包；它的 runtime 源码使用我们改造过的 agent-frontend-shell 项目，而不是旧的上游参考目录。

WebUI runtime 源仓库固定为：

~/hermes/agent-frontend-shell
remote: [email protected]:adv-org/agent-frontend-shell.git
branch: dev-zkp

~/hermes/hermes-webui 是旧的 nesquena/hermes-webui checkout，可作为历史参考， 但后续 WebUI 打包、离线 bundle 和 wrapper 集成都应以 agent-frontend-shell@dev-zkp 为准。

典型用法

交互式安装向导：

npx @bitseek/hermes-launchpad

向导会检查 Hermes 是否已安装、展示默认 pack 和 profiles、让用户选择要安装的 profile，选择安装后要激活的 profile，并提示输入必要的 API key。

脚本化安装：

npx @bitseek/hermes-launchpad import <pack-source>

<pack-source> 可以是本地目录、Git/GitHub 地址、npm 包名或 .tgz 包。 如果本机没有 Hermes，Launchpad 会委托官方 Hermes installer 完成安装，然后跳过 首次 hermes setup，改由 profile pack 里的预设配置完成模型、profile 和技能安装。

如果不传 <pack-source>，默认使用本仓库内置的钉钉 DWS trained pack：

npx @bitseek/hermes-launchpad import --yes --profile bitseek_im_dingding_assistant

也可以显式从 GitHub 子目录导入：

npx @bitseek/hermes-launchpad import github.com/adv-org/hermes-launchpad//packs/bitseek-default --yes --profile bitseek_im_dingding_assistant

CLI 命令

hermes-launchpad import <pack-source> [--yes] [--profile <name>]
hermes-launchpad import <pack-source> --all
hermes-launchpad import <pack-source> --activate-profile <name>
hermes-launchpad import <pack-source> --no-activate-profile
hermes-launchpad wizard [pack-source]
hermes-launchpad update [pack-name] [--yes]
hermes-launchpad diff <pack-source-or-pack-name>
hermes-launchpad doctor [profile-or-pack]
hermes-launchpad profiles
hermes-launchpad export <profile-name> --out <dir> [--include-memory-seed]
hermes-launchpad list
hermes-launchpad show <pack-name>

import 会把 pack 管理的文件复制到选中的 Hermes profile，并把安装元数据记录到 $HERMES_HOME/packs/。update 会基于这些元数据更新 pack 管理的文件。 不传 <pack-name> 时，update 默认使用当前 npm 包内置的 bitseek-default profile pack，先按 New profiles、Updated profiles、Conflicts / protected local edits 展示更新预览，再询问 Apply update? (Y)es / (N)o / (C)ancel [Y]:。本地已修改文件默认只保护， 不会被新版覆盖。

export 用于把一个已经调好的 Hermes profile 导出成可分享的 profile pack。 默认只导出配置、SOUL、自定义 skills、cron、skin 等可分发内容，不导出 Hermes 安装时自带的 bundled skills、会话、日志、工作区、密钥或记忆。确实需要导出记忆种子时，必须显式加 --include-memory-seed。

默认 trained profile pack

本仓库提供一个正式默认 pack：

packs/bitseek-default/
  pack.yaml
  profiles/
    bitseek_im_dingding_assistant/

它使用 trained profile 中提取并脱敏后的基础配置：

Provider: bitseek
Base URL: https://chat-proxy.bitseek.ai/v1
Chat completions URL: https://chat-proxy.bitseek.ai/v1/chat/completions
Model: QWEN3.6-Fast
Context window: 100K
Model secret env: BITSEEK_API_KEY

模型 API key 不会写入 pack。导入时可以通过环境变量提供，也可以由交互式流程提示用户输入。 钉钉等业务集成凭据不在导入阶段收集；用户真正使用 profile 后，由 profile 的 skill 通过对话引导配置。 后续 trained profile 应复用这个基础配置；新的 profile pack 只提取自己的 SOUL.md 和相对 Hermes 内置 skills/ 的 trained skill 差集。

导入 named profile 时，Launchpad 使用普通的 hermes profile create <name> 创建 profile， 让 Hermes 自动 seed 安装包自带的 bundled skills。Pack 本身不复制这些内置 skills，只安装 trained skill 差集；因此最终 profile 会同时拥有 Hermes 基础 skills 和 pack 提供的新 trained skills。 pack.yaml 里的 skill_policy 会描述这个策略，默认配置则放在 setup.presets。

安全边界

Launchpad 默认不会从 pack 安装这些用户私有或运行时状态：

• .env
• auth.json
• sessions/
• logs/
• workspace/
• home/
• .cache/
• runtime database 和 gateway/browser 状态

config.yaml 如果被用户本地修改，默认会保留本地修改；只有显式使用 --force-config 时才覆盖。记忆种子只在首次安装时写入，后续更新默认不会覆盖用户记忆。

测试

常规检查：

npm run check
npm run pack:dry-run

Docker Compose Linux 测试：

npm run test:compose:smoke
npm run test:compose:official
npm run test:compose:e2e

test:compose:e2e 会在 Linux 容器中跑完整链路：官方 Hermes 安装、profile 导入、 profile 更新、导出、全新 Hermes 环境再导入和 doctor 验证。

真实 provider 测试默认不跑，需要显式提供 key。Bitseek live 测试可用于校验 OpenAI-compatible chat completions endpoint：

BITSEEK_API_KEY=... npm run test:provider:live
BITSEEK_API_KEY=... npm run test:compose:e2e:live
BITSEEK_API_KEY=... npm run test:compose:webui-chat:live

默认钉钉 DWS pack 导入时只需要模型侧的 BITSEEK_API_KEY，并会写入用户选择安装的每个 profile，同时写入 root/default Hermes profile，保证 WebUI 和默认 profile 都使用同一套模型配置。 钉钉等业务集成凭据在 profile 使用时通过对话配置。test:compose:webui-chat:live 是完整 Docker 验证：在新容器里安装官方 Hermes Agent，输入 Bitseek 大模型 key，导入并选择 bitseek_im_dingding_assistant，本地打包安装 @bitseek/hermes-webui，启动 WebUI，并通过 WebUI API 发起一次真实对话。该流程仍会通过 launchpad doctor 做 Bitseek chat completions 探测，但会跳过 Hermes 原生 doctor 的全量第三方连通性检查；后者不认识自定义 Bitseek key， 且会检查与本 pack 无关的外部服务。live 测试会真实请求外部服务，因此不放进默认测试套件， 避免 CI 或本地测试依赖外部服务和长期密钥。

发布

发布前检查：

npm run release:check

正式发布建议使用 GitHub Actions 的 npm Trusted Publishing，不使用长期 npm token。 发布细节见 docs/RELEASE.md。

设计文档

当前设计和实现计划在 docs/plans/ 下维护。