@account-book/hermes-agent-kit
Hermes 实例接入账本（account-book）的安装与诊断工具。install 一条命令完成：
- 解析
mcp_servers.ledger的最终取值（参数 >config.yaml现值 > 默认值） - 只在有差异时写回
config.yaml，写前备份（权限 0600），写后保留原文件权限 - 同步账本 skill（
account-book，含references/指南）到HERMES_HOME/skills/，内容一致则跳过 - 检查
LEDGER_AGENT_TOKEN - 探测账本 MCP（
initialize/tools/list） - 打印后续步骤与回滚命令
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：LEDGER_AGENT_TOKEN=abk_agt_xxx -
目标 Hermes profile 目录（
HERMES_HOME）含config.yaml与.env
安装
# 首次安装
npx @account-book/hermes-agent-kit install \
--hermes-home /opt/data \
--account-book-url http://host.docker.internal:3721
如果 npx 无法解析 scoped 包的默认 bin，用显式形式：
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 会被完整覆盖，这是有意的破坏性变更；如确需白名单，需要后续单独设计。
常见用法
# 升级工具清单到最新全量（覆盖旧 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
帮助与版本
npx @account-book/hermes-agent-kit --help
npx @account-book/hermes-agent-kit --version
--help / --version 可以出现在任意位置，install --help 与 doctor --help 同样有效。
诊断
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），结束时打印回滚命令：
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 配置未实现，只输出建议。
开发
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