Aphanarc Hermes Launchpad

@aphanarc_lab/hermes-launchpad 是 Aphanarc 面向 Web2 团队的 Hermes Agent Profile 安装、升级和运维工具。

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

Workspace 约定

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

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

WebUI runtime 源仓库固定为：

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

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

典型用法

交互式安装向导：

npx @aphanarc_lab/hermes-launchpad

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

脚本化安装：

npx @aphanarc_lab/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 @aphanarc_lab/hermes-launchpad import --yes --profile bitseek_im_dingding_assistant

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

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

电商运营 Profile

电商运营专家已按既有规则加入默认 pack，但不会随默认安装自动导入。需要时用 --profile 指定；导入后会激活该 profile。若只安装、不切换当前 profile，可追加 --no-activate-profile。

npx @aphanarc_lab/hermes-launchpad import --yes --profile bitseek_e-commerce_e-commerce_operations_expert
npx @aphanarc_lab/hermes-launchpad import --yes --profile bitseek_e-commerce_e-commerce_operations_expert

该 profile 包含 15 个独立 skills。

CLI 命令

aphanarc-hermes-launchpad import <pack-source> [--yes] [--profile <name>]
aphanarc-hermes-launchpad import <pack-source> --all
aphanarc-hermes-launchpad import <pack-source> --activate-profile <name>
aphanarc-hermes-launchpad import <pack-source> --no-activate-profile
aphanarc-hermes-launchpad skill import <skill-directory> [--yes]
aphanarc-hermes-launchpad wizard [pack-source]
aphanarc-hermes-launchpad update [pack-name] [--yes]
aphanarc-hermes-launchpad upgrade [--yes] [--port <port>]
aphanarc-hermes-launchpad webui start [--port <port>] [--open]
aphanarc-hermes-launchpad webui status [--port <port>]
aphanarc-hermes-launchpad diff <pack-source-or-pack-name>
aphanarc-hermes-launchpad doctor [profile-or-pack]
aphanarc-hermes-launchpad profiles
aphanarc-hermes-launchpad export <profile-name> --out <dir> [--include-memory-seed]
aphanarc-hermes-launchpad list
aphanarc-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]:。本地已修改文件默认只保护， 不会被新版覆盖。

update 只更新 Profile pack，不更新 Hermes Agent 或 WebUI。受管组件升级统一使用 upgrade：Launchpad 会停止 WebUI、备份 WebUI 状态、把 Agent 切到锁定 commit、 通过自身精确依赖的 WebUI wrapper 重启，然后验证新进程身份、/api/profiles 和 /api/sessions。失败时会尝试恢复原 Agent commit 和 WebUI 状态。

upgrade 和 webui 统一使用 --port。升级时未传 --port 会优先复用 runtime.json 记录的当前 WebUI 端口；首次启动时 BitSeek 默认使用 9060，Aphanarc 默认使用 9061。--webui-port 暂时保留为 upgrade --port 的兼容别名，使用时会显示 弃用提示，并将在未来版本移除。

受管组件版本

Launchpad 0.1.48 锁定以下组合：

| 组件 | 锁定版本 | |---|---| | Hermes Agent | 0.15.1 / e1c7a9aa7b91b0c153022a7c8b55f1b469cf5c3b | | @aphanarc_lab/hermes-webui | 0.1.41 | | WebUI vendor | dcb722aef2e644c5163a78db2a23753c8fa4e20f |

不要直接运行全局 hermes-webui 或 npx @aphanarc_lab/hermes-webui@latest。统一通过 Launchpad 调用，确保不会被 PATH 中残留的旧版 0.1.17 覆盖：

aphanarc-hermes-launchpad webui start --port <port> --open
aphanarc-hermes-launchpad webui restart --port <port>
aphanarc-hermes-launchpad webui doctor --port <port>
aphanarc-hermes-launchpad doctor

Launchpad 启动 WebUI 时会写入 check_for_updates=false 和 ignore_agent_updates=true，并注入 managed 环境标记。当前 WebUI 上游尚未提供硬性 禁用 /api/updates/apply 的 managed-mode 契约，因此服务端 409 拦截仍需 WebUI 上游 配合；在此之前，受管发行版不应重新开启页面内更新检查。

skill import 用于把一个本地 skill 目录导入当前 Hermes Home 下的全部 profile， 包括根目录的 default profile。输入目录必须包含 SKILL.md；目录名就是写入 skills/ 下的 skill 名称。同名 skill 会先备份到 $HERMES_HOME/packs/launchpad/backups/skills/，再整体替换。非交互运行时需要加 --yes。导入前会校验路径、SKILL.md 是否为空，以及开头 YAML front matter（如有） 是否完整且可解析；校验失败时不会修改任何 profile，并会给出具体修正提示。

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

默认 trained profile pack

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

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

目录名已调整为 packs/bitseek-default-pack/。这个目录只保留 Launchpad pack 元数据，profile 文件来自 advokate-bitseek-hermes-profiles submodule 的 bitseek-default-profiles/。

它使用 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 test:components
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，本地打包安装 @aphanarc_lab/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/ 下维护。