# @account-book/hermes-agent-kit 中文文档

规范地址：https://npmcn.com/package/%40account-book/hermes-agent-kit/

版本：0\.0\.9
npm 元数据更新时间：2026-10-31T15:06:34.004Z
中文译文更新时间：2026-11-08T08:46:00.686Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40account-book/hermes-agent-kit
原文对照：https://npmcn.com/package/%40account-book/hermes-agent-kit/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：104 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-10-24T03:59:01.414Z
- 最新版本发布：2026-10-31T15:06:33.838Z
- 近 30 天下载量：1847（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Hermes 实例接入工具：合并 MCP 配置、安装 skills、探测连通、doctor 诊断

## 安装

```sh
npm install @account-book/hermes-agent-kit
```

也可以使用：`pnpm add @account-book/hermes-agent-kit`、`yarn add @account-book/hermes-agent-kit`、`bun add @account-book/hermes-agent-kit`

## README

# @account-book/hermes-agent-kit

Hermes 实例接入账本（account-book）的安装与诊断工具。`install` 一条命令完成：

1.  解析 `mcp_servers.ledger` 的最终取值（参数 > `config.yaml` 现值 > 默认值）
2.  只在有差异时写回 `config.yaml`，写前备份（权限 0600），写后保留原文件权限
3.  同步账本 skill（`account-book`，含 `references/` 指南）到 `HERMES_HOME/skills/`，内容一致则跳过
4.  检查 `LEDGER_AGENT_TOKEN`
5.  探测账本 MCP（`initialize` / `tools/list`）
6.  打印后续步骤与回滚命令

`LEDGER_AGENT_TOKEN` 是唯一需要手动写入的内容（`HERMES_HOME/.env`），安装器不会自动修改 `.env`。

已发布至 npm（`@account-book/hermes-agent-kit`），下文命令均可用 `npx` 直接运行；仓库内开发时也可用 `pnpm --filter @account-book/hermes-agent-kit exec node bin/install.js`。

## 前置条件

-   Node ≥ 20
    
-   账本服务端已部署，且 `<account-book-url>/internal/mcp` 可达（MCP 端点由服务端 `apps/server` 提供）
    
-   已用服务端 `agent:token issue` 签发实例 token，并写入 `HERMES_HOME/.env`：
    
    ```bash
    LEDGER_AGENT_TOKEN=abk_agt_xxx
    ```
    
-   目标 Hermes profile 目录（`HERMES_HOME`）含 `config.yaml` 与 `.env`
    

## 安装

```bash
# 首次安装
npx @account-book/hermes-agent-kit install \
  --hermes-home /opt/data \
  --account-book-url http://host.docker.internal:3721
```

如果 `npx` 无法解析 scoped 包的默认 bin，用显式形式：

```bash
npx -p @account-book/hermes-agent-kit hermes-agent-kit install --hermes-home /opt/data
```

### 取值规则

所有参数都是可选的，缺省按「`config.yaml` 现值 > 内置默认值」回落：

| 参数 | 不传时的取值 | 说明 |
| --- | --- | --- |
| `--hermes-home` | `$HERMES_HOME` / `~/.hermes` | Hermes profile 目录 |
| `--account-book-url` | `config.yaml` 现值 / `http://host.docker.internal:3721` | 账本服务端基地址（自动补 `/internal/mcp`） |
| `--profile` | `default` | 预留；当前版本直接操作 `--hermes-home` 指向的目录 |
| `--force` / `--reset` | 否 | 忽略现值，把 `mcp_servers.ledger` 整段重建为模板值（不影响 skills） |
| `--dry-run` | 否 | 全程只读，打印 diff 与计划，不写任何文件 |
| `--restart` | 否 | 首版未实现自动重启，结束时提示手动重启 gateway |
| `--mode` | `http` | 仅支持 `http`；stdio 转发器首版未实现（模板中留有注释占位） |

`install` 只管理 `mcp_servers.ledger` 下的 `url` 与 `tools.include` 两个字段。`timeout`、`lazy`、`trust` 这类字段一旦存在于配置里就保持原样，不会被覆盖。

`tools.include` 始终写入全量 13 个工具（不再提供 `--tools` / `p1` / `all`）。升级旧实例时旧 include 会被完整覆盖，这是有意的破坏性变更；如确需白名单，需要后续单独设计。

### 常见用法

```bash
# 升级工具清单到最新全量（覆盖旧 include），地址沿用 config.yaml 现值
npx @account-book/hermes-agent-kit install --hermes-home /opt/data

# 只更新 skills：不传配置参数，config.yaml 一个字节都不会变
npx @account-book/hermes-agent-kit install --hermes-home /opt/data

# 先看会改什么，不写盘
npx @account-book/hermes-agent-kit install --hermes-home /opt/data --dry-run

# 配置乱了，恢复成模板值
npx @account-book/hermes-agent-kit install --hermes-home /opt/data --force
```

## 帮助与版本

```bash
npx @account-book/hermes-agent-kit --help
npx @account-book/hermes-agent-kit --version
```

`--help` / `--version` 可以出现在任意位置，`install --help` 与 `doctor --help` 同样有效。

## 诊断

```bash
npx @account-book/hermes-agent-kit doctor --hermes-home /opt/data
```

逐项输出 `ok / warn / fail`：Node 版本、`HERMES_HOME`、`config.yaml` 可解析、`mcp_servers.ledger`、`LEDGER_AGENT_TOKEN`、MCP `initialize`、`tools/list` 数量、skills 目录。有任何 `fail` 时退出码为 1。

## 手动配置兜底

安装器无法访问 `HERMES_HOME`（远程实例、权限不足）或 `config.yaml` 结构特殊时，把 `templates/mcp-snippet.yaml` 渲染后手工并入 `config.yaml` 的 `mcp_servers:` 段，skills 手动复制到 `HERMES_HOME/skills/account-book/`（保持目录结构，含 `references/`）。

## 回滚

只有真正写盘时才会生成 `config.yaml.bak.<UTC 时间戳>`（权限 0600），结束时打印回滚命令：

```bash
cp /opt/data/config.yaml.bak.20261023T120000 /opt/data/config.yaml
```

配置没有任何变化时不备份、不改文件，所以反复运行不会堆出一堆备份。

## skills 同步规则

-   目标 skill 不存在：复制。
-   已存在且每个文件内容都与包内一致：跳过。
-   已存在但内容有差异：覆盖（用于升级指南文件）。
-   不删除 `HERMES_HOME/skills/` 下的其他 skill，也不清理包内已移除的旧文件。
-   `--force` 不影响 skills：它只重建 `mcp_servers.ledger`。

## 安全注意

-   token 不进 `config.yaml`：配置里只写 `${LEDGER_AGENT_TOKEN}` 运行时占位符，由 Hermes 在连接时从环境变量解析。
-   不改 `config.yaml` 的权限：原子写（`.tmp` + rename）沿用原文件的 mode，安装前后权限一致。
-   安装器只打印「已配置 / 未配置」，不回显 token 值，也不自动修改 `.env`。
-   安装器只请求 MCP `initialize` 与 `tools/list`，不访问账本业务接口。

## 范围与限制（P0）

-   仅 HTTP 模式；stdio 模式只在模板中留有注释占位，`mcp` 转发子命令未实现。
-   `--restart` 未实现自动重启，需要手动重启 gateway。
-   多 profile（`--profile`）布局未支持，操作目标是 `--hermes-home` 目录本身。
-   自动收窄 toolset / memory 配置未实现，只输出建议。

## 开发

```bash
pnpm --filter @account-book/hermes-agent-kit build    # 产出 dist/（bin 入口依赖它）
pnpm --filter @account-book/hermes-agent-kit test
pnpm --filter @account-book/hermes-agent-kit lint
pnpm --filter @account-book/hermes-agent-kit typecheck
```

## 常见问题

### @account-book/hermes-agent-kit 是什么？

Hermes 实例接入工具：合并 MCP 配置、安装 skills、探测连通、doctor 诊断

### 如何安装 @account-book/hermes-agent-kit？

在项目目录运行 npm install @account-book/hermes-agent-kit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 hermes-agent-kit，可以用 npx hermes-agent-kit 直接运行。

### @account-book/hermes-agent-kit 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/account-book\_\_hermes-agent-kit 是否存在。

### @account-book/hermes-agent-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @account-book/hermes-agent-kit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @account-book/hermes-agent-kit 可以商用吗？

@account-book/hermes-agent-kit 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @account-book/hermes-agent-kit 的下载量有多少？

根据 npm 官方下载统计，@account-book/hermes-agent-kit 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,847 次，日均约 62 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @account-book/hermes-agent-kit 还在维护吗？

最新版本 0\.0\.9 发布于 2026/10/31（7 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/10/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。