# @crvouga/mockingbird-service-hermes 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-hermes/

版本：1\.11\.0
npm 元数据更新时间：2026-11-11T02:17:00.231Z
中文译文更新时间：2026-11-11T05:57:00.176Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-hermes
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-hermes/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/hermes#readme
源码仓库：https://github.com/crvouga/mockingbird

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

- 包体积（解压后）：4.4 MB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-10-05T09:26:16.422Z
- 最新版本发布：2026-11-11T02:16:59.810Z
- 近 30 天下载量：3040（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

Hermes 同行运行的 API 模拟器带有可移植脚本的生命周期控制.

## 安装

```sh
npm install @crvouga/mockingbird-service-hermes
```

也可以使用：`pnpm add @crvouga/mockingbird-service-hermes`、`yarn add @crvouga/mockingbird-service-hermes`、`bun add @crvouga/mockingbird-service-hermes`

## README

# @crvouga/ mockingbird-service-hermes (英语)

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

Hermes代理公司公共同行运营的API在建模拟器 `v2026.8.31`提交、投票和停止工作,同时明确进行合成生命周期观察. 事件、批准和引导仍然得不到支持。 没有代理或推论运行. [API 证据.md](https://npmcn.com/package/%40crvouga/mockingbird-service-hermes/API_EVIDENCE.md) 记录来源支持的语义和空白; [支助](https://npmcn.com/package/%40crvouga/mockingbird-service-hermes/SUPPORT.md) 记录当前操作支持.

## 安装

```sh
bun add @crvouga/mockingbird-service-hermes
```

## 使用量

```ts
import { createServer } from "@crvouga/mockingbird-service-hermes/server"

// Test setup: the emulator on an ephemeral loopback port.
const server = await createServer({ seed: 42 })

// Application code: the peer HTTP client's base URL is server.url.
const baseUrl = server.url
const accepted = await fetch(`${baseUrl}/v1/runs`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ input: "synthetic prompt" }),
})
console.log(await accepted.json()) // { run_id, status: "started", replayed: false }
await server.close()
```

使用便携式 `HermesAPI` 仅供供应商使用. `createRuntime` 添加健康、 命名空间、 管理控制、 断层、 时钟、 度量器、 仅元数据 并共享时间线检查站。 它不需要赫尔墨斯安装, 提供者账户,即时数据,API密钥,或本地服务. 没有听众, `createRuntime().fetch(request)` 服务于相同过程中的路径.

管理员控制共享源 :

```ts
import { createServer } from "@crvouga/mockingbird-service-hermes/server"

const server = await createServer() // ephemeral loopback port
try {
  console.log(await (await fetch(`${server.url}/__admin/health`)).json())
} finally {
  await server.close()
}
```

CLI是: 校对: `mockingbird-hermes serve --port 8827`。指向 HTTP 客户端的基础 URL 时间 `http://127.0.0.1:8827`;在执行队列直到脚本时立即提交返回. 节点条目与可移植获取条目是分开的.

## 路线和控制

`POST /v1/runs` 承认逃跑 `GET /v1/runs/{run_id}` 民意调查. `POST /v1/runs/{run_id}/stop` 请求中断。 活动、核准和引导 返回一个只使用模拟器的501个信封 `error.type` 联 合 国 `mockingbird_unsupported` 财务报告和审定财务报表 `error.code` 联 合 国 `operation_not_implemented`。 。 。 . 丢失的运行使用被绑 `run_not_found` 404号信封. 返回未知路径 404. 只有模拟器的错误并不声称有真正的Hermes拒绝行为.

-   `GET /__admin/health` 识别 `hermes` 运行时间.
-   选择孤立的命名空间 `x-mockingbird-namespace` 或者说 `/__admin/ns/<name>/…`。 。 。 .
-   `POST /__admin/reset` 清除选中的提供者状态和时间线。 共享时钟, 断层和诊断期刊保留其标准的独立寿命.
-   `POST /__admin/clock` 控制共享时钟.
-   `POST /__admin/faults` 配置范围操作/路径/方法故障规则; `DELETE /__admin/faults` 清除他们。 命名为 Hermes 的预设在下面记录 .
-   `GET /__admin/requests` 显示请求的元数据, 查询值 或全权证书. `DELETE /__admin/requests` 清除选定的诊断历史.
-   `POST /__admin/checkpoints` 抓取共享的时间线状态 。 通过检查 `POST /__admin/branches/<name>/checkout` 与 `{ "checkpoint": "cp_…" }`。 。 。 .

现有共享 `adminKey` 选项控制管理员访问。 没有基于证书的 名称空间映射或 Hermes 提供者认证逻辑被引入.

## API 密码

便携式进口:

-   `HermesAPI`: 提供者 `fetch` 财务报告和审定财务报表 `reset`,带有命名空间并共享 SQLite 存储.
-   `HERMES_NAMESPACE`: 默认存储命名空间, `hermes`。 。 。 .
-   `createRuntime`:标准服务运行时间和共享控制.
-   `document`:附加说明的OpenAPI合同.
-   `operationIds`:所有清点操作.
-   `supportedOperationIds`数字 : `RunCreate`, (中文(简体) ), `RunGet`,以及 `RunStop`。 。 。 .

只有节点 `/server` 条目导出 :

-   `createServer`: 返回 `runtime`, (中文(简体) ), `server`, (中文(简体) ), `url`, (中文(简体) ), `host`, (中文(简体) ), `port`,以及 `close`。 。 。 .
-   `DEFAULT_PORT`: CLI默认为8827;程序调用默认为麻黄口.
-   `serveTarget`:共享 CLI 服务器目标.

类型包括: `HermesAPIOptions`, (中文(简体) ), `HermesRuntime`, (中文(简体) ), `HermesRuntimeOptions`, (中文(简体) ), `OperationId`, (中文(简体) ), `SupportedOperationId`, (中文(简体) ), `HermesServer`,以及 `HermesServerOptions`。 。 。 . 可执行文件 `mockingbird-hermes` 提供 `serve`。 。 。 .

## 脚本运行

```ts
import { createServer } from "@crvouga/mockingbird-service-hermes/server"

const server = await createServer({ seed: 42 })
const baseUrl = server.url
const json = { "content-type": "application/json" }

// Application code: submit a run.
const accepted = await fetch(`${baseUrl}/v1/runs`, {
  method: "POST",
  headers: json,
  body: JSON.stringify({ input: "synthetic prompt" }),
})
const { run_id } = (await accepted.json()) as { run_id: string }

// Test control: script the outcome. No agent runs, so nothing moves until you do.
await fetch(`${baseUrl}/__admin/hermes/runs/${run_id}/observe`, {
  method: "POST",
  headers: json,
  body: JSON.stringify({ status: "completed", output: "synthetic result" }),
})

// Application code: poll the run.
const status = await fetch(`${baseUrl}/v1/runs/${run_id}`)
console.log(await status.json())
await server.close()
```

入学返回 `{ run_id, status: "started", replayed: false }`存储 状态开始于 `queued`重复投票不会推进执行或时间. 在提交、观察和投票时使用相同的命名空间。 可选 `session_id` 缺勤或虚伪时默认运行的ID. `model` 默认为 `hermes-agent` 仅当不存在时; 保留明确的无效或空值, 如 在被钉住的操纵器里。 一个有效的 `X-Hermes-Session-Key` 被反射而不产生 对话 ID 或认证证书。 模式路由和记录 没有模拟。 ID是决定性不透明六分弦,与会话分开.

观察控制器接受 `status`数字 : `queued`, (中文(简体) ), `running`, (中文(简体) ), `waiting_for_approval`, (中文(简体) ), `stopping`, (中文(简体) ), `completed`, (中文(简体) ), `failed`, (中文(简体) ), `cancelled`,或 `interrupted`它接受可选 `last_event`· ; `approval` 只在等待的时候; `error` 仅用于失败/中断 `output`, (中文(简体) ), `usage`, (中文(简体) ), `pending_steer` 仅限 已完成。 用法有三种非负整数: `input_tokens`, (中文(简体) ), `output_tokens`, (中文(简体) ), `total_tokens`。完成默认为空输出和零计数. 终端观测不能改变(409);无效的控制有效载荷返回400 不改变状态。 这些是模拟器控制,而不是额外的赫尔墨斯路线.

时间戳为Unix秒从共享时钟. 运行记录及其身份 序列使用共享存储和时间线;重置后清除. 没有计时器, 代理 手柄或提示被存储。 投票结果内容不在日记. 根部/最后输入元素、主机室和无效内存镜头 目前返回明确的模拟器只501个响应。 见这些限度的证据.

## A. 同上文的提交和合成范围

发送 `Idempotency-Key` 准备送货 相同的复试返回 202 与 原始运行的ID,其当前状态, `replayed: true`,以及 `Idempotency-Replayed: true`。带有相同范围密钥返回的已改变的有效载荷 409个 `idempotency_key_conflict`。同时期相同的请求保留一次运行. 空/ 空白密钥禁止分解; 其他密钥必须包含 1–255 可见 Python风格修饰后的ASCII字符. 校验错误不保留任何内容 .

指纹覆盖了整个解剖的JSON尸体, 包括未知的字段, 被修剪的 `X-Hermes-Session-Key`。对象密钥顺序无关紧要;数组 顺序和会话/体位的更改。 原始整数/浮取形式跟随 Python : `1` 财务报告和审定财务报表 `1.0` 冲突, `1.0` 财务报告和审定财务报表 `1e0` 重放, 负浮零不同 从正零。 Lone Unicode 代词返回一个明确的仿真器,只返回 501; Python 无法将 UTF-8 编码为指纹 .

`POST /__admin/hermes/scope` 与 `{ "profile": "synthetic-profile", "identity": "synthetic-listener" }` 在 当前的鸟类命名空间。 默认为 `default` 财务报告和审定财务报表 `unauthenticated-test-listener`。只使用合成标签,不使用证书. 改变范围将保留地和公共投票隔开;恢复范围 进入它的运行。 会话ID和内存密钥不是范围选择器,而且 无记名文本被忽略 。 此控制不执行认证 .

保留地和拥有地在重建 `HermesAPI` 同样的 SQLite客户端和命名空间. 终端重播在建模后进行校验 适配器重建. 实际进程/磁盘耐久性和未完成的重新启动 模拟结果的是下面明确的重新启动控制。 共享 时间线恢复了范围,保留并一起运行记录;重新设置清除. 没有添加公共密钥搜索端点 。 请求体被用散列来记忆和 - 存储的保留包含关键、散列、运行身份和持久观察.

## 停止和逻辑重新启动

`POST /v1/runs/{run_id}/stop` 返回 200 `{ run_id, status: "stopping" }` 页:1 当地积极工作。 重复的停止请求保持中间状态。 使用 `observe` 脚本最终结果 : `cancelled` 对于承认中断, `completed` 当正常完成赢得比赛时,或 `failed` 用于执行失败. 停止终端运行返回其完全不变状态,而不是重新取消 . 丢失或无法进入的运行返回 404 `run_not_found`。 。 。 .

`POST /__admin/hermes/restart` 与 `{ "owner": "stale" }` 模型损失 当前命名空间的网关。 它丢弃缓存的观测结果, 并保留幸存的可持久键 该名称空间中所有合成剖面的保留。 未完成的按键 运行成为 `interrupted` 当下一次调查、重播或停止时 `The gateway restarted before this run settled.` 财务报告和审定财务报表 `run.interrupted`。 。 。 . 其创建时间戳保持不变;其更新时间戳反映了第一个 观察。 终端运行保留其状态和结果. 重试旧货 键重放被中断的运行; 新键创建了不同的运行.

使用 `{ "owner": "alive" }` 在网关替换后模拟另一个现场主人. 密钥观察保持不变, 但停止未完成的外国工作返回 409个 `run_not_active`明确 `observe` 能代表主人的终极 已完成。 无论是读取 PID 、 中断一个真正的进程, 还是运行一个代理 . 这是合乎逻辑的假设,而不是过程/磁盘耐久性保证。 共享时间线 恢复所有者旗并运行/保留状态.

## 保留和历史

受控时钟管辖两个独立的保留层. 缓存 `completed`, (中文(简体) ), `failed` 财务报告和审定财务报表 `cancelled` 更新年龄越大的结果过期 1小时以上;平等生存 `interrupted` 除外。 模拟器评价 在无背景的情况下,在进入或观察时扫描了60秒 进程. `POST /__admin/hermes/sweep` 与 `{}` 明确执行一次扫描 当前时钟, 返回 `cacheRemoved` 财务报告和审定财务报表 `simulated: true`。 。 。 .

键入式终端预订仅在其持久更新年龄严格时到期 超过24小时。 有效的按键录入触发了这种干扰,包括 请求随后发生冲突。 投票和没有钥匙的录取并不严格 持久行. 积极的保留从不因年龄而过期。 投票可以恢复一个 缓存拆迁后保留耐用结果,甚至超过24小时; 缓存结果也可能暂时超过其被挤压的保留。 缺少结果 返回普通的 404 `run_not_found`,没有发明过期状态.

相同状态进度观测更新缓存时间戳,但不持久 新的进度有效载荷,除非选定的可持久域发生变化。 逻辑重启 清除缓存的观测结果和水合物,仅能幸存持久行. 时间线 恢复两层,所有权,扫描时间表和控制的时钟. 这些是共享存储和逻辑重起保障,而不是进程崩溃或磁盘 耐久之证. SSE缓冲器和主机房保留仍留在子集外.

## 过失和消费者情况

使用 `POST /__admin/faults` 与 `{ "preset": "hermes_submit_accepted_drop" }` 改为 接受一次新的运行,失去反应。 共享日记记录接受和 其检查站,尽管交货失败。 重试同一体和独能键 以恢复原运行。 校验失败仍然返回正常错误 .

其他一发预设是: `hermes_poll_timeout` (推迟一次民意测验 1 000 ms), `hermes_throttled` (429带有被绑定的默认容量信封),以及 `hermes_draining` (503与被钉入排水口袋). 两种拒绝预设 包含 `Retry-After: 1` 并跑在录取前。 这些是明确的设想; 它们不会自动计算容量或模拟真正的排水网关. 要脚本执行器失败, 请使用 `observe` 与 `status: "failed"` 合成 `error` 文本,然后投票或重播相同的运行.

节点HTTP消费者固定器拥有一次性服务器并使用独立的 HTTP 客户端可以测试丢失的响应,重播,投票,停止,客户端最后期限和 过期。 它不进口 " 倡议 " 或强制实行消费者再试验政策。 财产 比较合格的同行业务和坚持覆盖范围 注入有计划的有效生命周期差异,以测试参照国。 自我平等是 一致性证据,而不是独立的 Hermes 运行时兼容性索赔.

## 故意不模拟

提示、指示和历史经过验证后被丢弃. 合成结果文本可以通过观测控制来存储并被重置来清除. Kanban尝试,客户接收/回收政策,推断,Python调度员, 不包括主机工具执行和证书执行。 没有出口 网络用户、服务商或代理程序。 公共同行管理身份证将保留 与消费者摄取量和Kanban身份无关.

原始证据不是运行时间均等。 包/共享控制测试没有建立 与真实的Hermes进程兼容。 选入 [被钉住的甲骨文](https://npmcn.com/package/%40crvouga/mockingbird-service-hermes/oracle/README.md) 单独通过33个有记录的公开HTTP 比较,包括新进程 SQLite 重新启动;其替换和 限制仍然是明确的。 保持这个包WIP,直到满足独立的就绪要求.

## HTTP 重放实例

开始 `mockingbird-hermes serve --port 8827`,然后提交合成投递:

```sh
curl -sS http://127.0.0.1:8827/v1/runs \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-delivery' \
  -d '{"input":"synthetic prompt"}'
```

重复相同的请求返回相同的 `run_id` 和重播标题. 票价 `GET /v1/runs/<run_id>`; 请求中断使用 `POST /v1/runs/<run_id>/stop`停止反应是中间的。 填写 假设 `POST /__admin/hermes/runs/<run_id>/observe`使用 JSON 机体 例如 `{ "status": "cancelled" }`然后再次投票。 只使用合成输入 和结果数据。 不需要Python调度器或Kanban集成.

## 核查和证据

包裹还在 **妇女**6个库存业务中有3个得到支持; SSE事件、核准执行和引导仍然排除在外。 运出 [甲骨文指南](https://npmcn.com/package/%40crvouga/mockingbird-service-hermes/oracle/README.md), (中文(简体) ), [源代码表](https://npmcn.com/package/%40crvouga/mockingbird-service-hermes/oracle/source-lock.json),以及 [记录的比较](https://npmcn.com/package/%40crvouga/mockingbird-service-hermes/evidence/pinned-oracle.json) 制作准确的上游针 和可检查的替代物。 仅在单独授权后运行预告 其依赖性、可支配数据库和处理操作。 普通包装测试 不需要这些业务或供应商证书.

从此仓库运行 `bun test packages/service/hermes` 和包裹的 `typecheck`, (中文(简体) ), `lint`, (中文(简体) ), `generate:check`, (中文(简体) ), `openapi:check`, (中文(简体) ), `build`, (中文(简体) ), `portability` 财务报告和审定财务报表 `pack:check` 剧本. 根号 `bun run check` 还验证目录和生成 文档新鲜度。 文件目录游乐场使用相同的便携式 运行时间;其状态为本地到浏览器.

## 常见问题

### @crvouga/mockingbird-service-hermes 是什么？

Hermes 同行运行的 API 模拟器带有可移植脚本的生命周期控制\.

### 如何安装 @crvouga/mockingbird-service-hermes？

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

### @crvouga/mockingbird-service-hermes 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @crvouga/mockingbird-service-hermes 支持 ESM 还是 CommonJS？

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

### @crvouga/mockingbird-service-hermes 可以商用吗？

@crvouga/mockingbird-service-hermes 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @crvouga/mockingbird-service-hermes 的下载量有多少？

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

### @crvouga/mockingbird-service-hermes 还在维护吗？

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