# jg-agent-hq 中文文档 规范地址：https://npmcn.com/package/jg-agent-hq/ 版本：11\.1\.0 npm 元数据更新时间：2026-11-03T22:42:41.766Z 中文译文更新时间：2026-11-03T23:08:34.800Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/jg-agent-hq 原文对照：https://npmcn.com/package/jg-agent-hq/?lang=original 项目主页：https://github.com/jesusgraterol/jg-agent-hq#readme 源码仓库：https://github.com/jesusgraterol/jg-agent-hq ## 关键信息（来自 npm 元数据） - 包体积（解压后）：2.1 MB，422 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=24\.15\.0 - 运行依赖：6 个 - 首次发布：2026-10-20T17:55:57.288Z - 最新版本发布：2026-11-03T22:42:41.418Z - 已发布版本数：45（近 12 个月 45 个） ## 中文简介 本地Claude Code和Codex会话控制，历史，使用和可恢复的本地存储为Node.js应用。 ## 安装 ```sh npm install jg-agent-hq ``` 也可以使用：`pnpm add jg-agent-hq`、`yarn add jg-agent-hq`、`bun add jg-agent-hq` ## README # jg-agent-hq TypeScript库和本地控制器，用于运行编码代理的应用程序。创建本地Claude Code和Codex会话，发送工作，处理权限，并通过一个API跟踪结果。 使用它来构建代理仪表板、编辑器集成或自动化开发工作流。总部拥有本地会话控制权。您的应用程序拥有自己的接口、身份验证和机外备份。本地cli提供编码工具、工具、技能和登录；其他提供者可以实现相同的主机契约。 Linux或macOS需要Node.js 24.15.0或更高版本。锁协议使用POSIX所有权、私有目录和进程活动探测。Windows不在受支持的主机契约范围内。 ## 安装 本地安装包： ```sh npm install jg-agent-hq npx jg-agent-hq serve --state-root .runtime --workspace-root . ``` 分别安装Claude Code和/或Codex，并通过其本地cli登录。在您信任的工作区中运行控制器。下面的CLI示例假设安装的可执行文件位于PATH；加上前缀 `npx` 用于本地NPM安装。 这个公共包提供了一个本地控制器和浏览器安全的契约。应用程序拥有自己的UI、身份验证和部署。它不包括托管应用程序或Moldea UI下载。 ## 发展 使用pnpm 12.4.0。运行 `pnpm install`,然后 `pnpm check:package` 要构建，请执行构建的API和打包的消费者，类型检查和格式检查。 `pnpm test:unit` 和 `pnpm test:integration` 在构建之后选择它们自己的类别。私人网站工作区有单独的检查；安装Chromium `pnpm --dir website exec playwright install chromium`，然后跑 `pnpm --dir website check`。 `pnpm check` 在两方面都有突破。 工作 `development`;评审的变更范围 `main` 通过拉请求。在两个Node检查通过之后 `main`， `check.yml` 通过npm配置的可信发布器发布经过消费者测试的压缩包，然后部署网站。不需要本地npm登录或令牌。跳过了相同的已发布版本；更改的内容需要新版本。 ## 测试 `pnpm test`， `pnpm check:package`, `pnpm check` 进行必要的报道。他们的 `:full` 对应方保留完整的包或包/网站检查。粒度和集中的命令在默认情况下保持完整。仅在明确请求时在本地完整运行；看到 [测试策略](https://github.com/jesusgraterol/jg-agent-hq/blob/main/docs/testing.md) 用于分类和受影响的消费者检查。 当只有这六个聚合脚本和这个标记的测试命令块不同时，测试维护可以重用现有的版本。所有运行时文件、依赖项、导出、安装脚本、其他文档和文件权限仍然受到发布检查的保护。上述一般版本规则的这一狭隘例外跳过了出版；它不会改变已安装的包。 ## 锁的所有权 调用者提供可信状态根。锁住它的私处 `.runtime/hq.lock`． 持有人记录其进程ID、nonce、安全操作标签和创建时间。等待活的持有者。已死的、不完整的或无法验证的所有者需要检查，并且永远不会自动回收，因为子进程可能保持活动状态。一个例外是运行时停止而不释放状态根：当主机的 `isPreviousRuntimeStopped` 检查证明该运行时的进程不存在，下一个运行时将替换其所有者记录，并移除持有者不再存在的锁和它留下的套接字。主机保证一次最多有一个调用方回收给定的状态根。 短元数据操作使用 `withHqLock`． 长期运行时所有权必须使用单独的所有者记录；永远不要在代理回合的生命周期内持有元数据锁。该锁协调协作进程，并且不会隔离作为同一操作系统用户运行的恶意代码。 机器范围的锁是分开的。这个 `locks` 阅读和 `jg-agent-hq locks` 列出机器上的脚本、代理和应用程序通过的已命名锁 [jg-locks](https://jg-packages.jesusgraterol.dev/packages/jg-locks/)，每个都有它的持有者，所以HQ上的应用程序可以显示它们。总部只读取它们；它从不占用、等待或恢复一个。看到 [机锁](https://npmcn.com/package/jg-agent-hq/api/README.md#machine-locks)。 看到 [API参考](https://npmcn.com/package/jg-agent-hq/api/README.md) 和 [错误的合同](https://npmcn.com/package/jg-agent-hq/errors/README.md)。 故意失败使用 `Exception` 从 `jg-exception`，使用错误引用中的命名字符串代码。本地客户端使用 `PUBLIC_ERROR_CODES` 和 `PUBLIC_ERROR_MESSAGES` 从 `jg-agent-hq/contracts` 在IPC边界翻译的错误。安全分类仍然与私人诊断原因分开。 ## 本地控制器 安装所需的提供程序，并通过它们的本机cli登录，然后启动 `jg-agent-hq serve --state-root .runtime --workspace-root /path/to/workspace`。运行 `jg-agent-hq status --state-root .runtime` 在客户端。 `threads`， `thread`， `turns`， `items` 和 `usage` 读取本地信息，每个条目都带有时间 `createdAt`。 `item-detail` 读取开发人员在一个项目中检查的内容：它的命令和输出、工具调用、文件差异和图像，以及 `item-image` 返回其中一个图像。 `stop` 等待确认的运行时关闭。 Node API公开了 `createAgentHq({ stateRoot, allowedRoots })` 和 `requestAgentHq(stateRoot, command)`． 配置来自这些受信任的操作员输入。编码指令文件不是运行时配置。 控制器拥有独立于客户端连接的SQLite工作器和本机连接。它的提供程序注册中心仅在选择时启动每个本机集成。存储和托管会话读取无需安装编码CLI即可工作；不可用的提供程序不会禁用另一个提供程序。私有状态包含生存期所有者、Unix套接字和SQLite发现元数据。 会话历史记录保存在本机存储中；总部在他们的行动收据上保留完整的有界最终结果。浏览永远不会恢复外部会话或启动推理。配额窗口来自本地帐户观察，具有显式的陈旧和不可用状态。使用读数包括食品法典信用余额和报告时可用的赚取重置计数，加上克劳德五小时和七天表及其模型/表面范围和重置时间。 使用 `sessions` 为了发现和 `session-evidence` 最新的历史证据。这些读取适合65,536个序列化字节，保留精确的本机标识和内容散列，并以UTF-8块继续读取大型主体。选择一个项目，打开或项目类型与过滤器。匹配的名称仍然是单独的会话。来源区分原生证据与确切宿主提交的证据；历史文本和引用的反馈从未获得批准。看到 [有界会话证据](https://npmcn.com/package/jg-agent-hq/api/README.md#bounded-session-evidence)。 受信任的节点主机可以打开由 `hq.storage` 并将应用程序表置于自己的前缀之下。总部储备 `hq_`，在启动时验证其当前模式戳，并保留应用程序模式所有权和 `user_version` 和主人一起。使用 `hq.withStorageMaintenance(callback)` 对于主机模式更改；它在回调之前耗尽已接受的工作并拒绝活动的本机执行。印章记录编写数据库的包版本，并且startup拒绝任何其他命名该版本错误的模式；HQ从不迁移存储。看到 [共享存储契约](https://npmcn.com/package/jg-agent-hq/api/README.md#shared-storage)。 `createHqSnapshot(hq, destination)` 在代理保持工作的同时，通过SQLite的备份API捕获本地状态，包括主机表和操作。钥匙，在总部状态下锁定根；主机保持自己的连接不写主机表，直到它解析。它省略了Claude转录的索引，恢复的运行时根据其第一次Claude历史读取的转录重新构建该索引，就像新运行时一样。 `inspectHqSnapshot(directory)` 验证完整的快照； `restoreHqSnapshot({ snapshotDirectory, destination })` 验证它并将其分阶段到一个新的私有恢复工作区。 `packHqSnapshot(snapshotDirectory, archivePath, key)` 将快照加密为一个AES-256-GCM文件，用于机外副本 `unpackHqSnapshot(archivePath, destination, key)` 验证并将其作为快照目录写回。来自另一个模式的快照被编写它们的包版本拒绝。恢复本地所有权需要和解，允许的根必须明确选择。主机拥有密钥和远程备份；失败的磁盘可能会丢失自上次成功的脱机备份以来所做的更改。看到 [快照和恢复](https://npmcn.com/package/jg-agent-hq/api/README.md#snapshot-and-restore) 和 [复苏](https://npmcn.com/package/jg-agent-hq/docs/recovery.md)。 会议也是在终端上开始的。共享守护进程的法典会话和克劳德会话 `claude agents --json` 报告一个活动状态(`running`， `waiting`， `idle`， `closed`， `failed` 或 `unknown`)与外部所有权。HQ建立在每个CLI提供的基础上，并且永远不会停止、唤醒或驱动终端运行的会话：它采用终端在回合之间通过共享守护进程保持的Codex会话，并且只有在没有终端运行它时才使用Claude会话，而Claude会话是 `terminal` 字段命名执行该操作的终端。被管理或观察会话的每个状态变化都按顺序记录；阅读它们 `{ kind: 'session-states', afterSequence }` 或 `session-states`。 `active-sessions` 列出每个运行和等待会话及其工作空间， `unstarted-threads` 列出了HQ在他们的第一个回合之前创建的会话 `observation-pace` 每5秒对克劳德进行一次投票，而不是30秒，同时有客户在现场观看。看到 [会话状态](https://npmcn.com/package/jg-agent-hq/api/README.md#session-states)。 提供者id是有界的小写标识符。法典和克劳德是内置的；受信任的节点主机可以额外注册 `IAgentProviderFactory` 实现通过 `providerFactories`． 功能报告当前操作支持、提供者/会话范围和不可用原因。本机版本标签是诊断性元数据，从不决定是否允许。未知的基本控制数据显式失败。 `jg-agent-hq/contracts` 包含浏览器安全的模式和类型；导入它不会导入主机运行时。 使用 `--provider claude` 了解克劳德的历史和用法；默认值为 `codex`． Claude通过其本地结构化CLI惰性连接，启用了正常设置，没有用户提示。历史读取仅在运行时第一次检查CLI时启动该进程，并且使用结果将在60秒内响应读取。使用请求显式禁用可选的转录行为扫描。 它的本地历史读取器验证所需的身份、工作空间和链字段，允许添加字段和混合版本标签，在SQLite中保留字节位置而不是会话主体，并且不会为未更改的记录写入任何内容。历史记录、活动项和证据以CLI显示的方式呈现项 `notice` 项，工具调用与其结果配对，以及每个文件更改的文件；未知排序的内容表示为不受支持，不可信的标识或排序使受影响的读取不可用。文件历史记录无法建立当前执行状态。看到 [读者限制和新鲜度收缩](https://npmcn.com/package/jg-agent-hq/api/README.md#claude-history)。 明确的动作创建、命名、采用、恢复和关闭线程；发送空闲消息；精确地转向；将下一条消息排队；中断;并回答本地问题，许可或MCP引出。操作具有稳定的uuid和持久的收据。 `action-wait` 一旦它有了自己的本地线程ID，或者被HQ自己的更改而不是轮询唤醒，或者当它的超时时间（最多30秒）过去时，它就会返回收据。重复相同的请求返回其收据；更改UUID的有效负载冲突。丢失的确认将保持不确定状态，直到确切的本地响应到达或操作人员做出明确的恢复选择。总部从不重新发送不确定的输入。 操作还将本机历史拆分为一个单独的会话，压缩空闲会话，并在支持的情况下使用本机存档/解存档和历史还原。福克斯保留了确切的本土血统。在显式恢复之前，取消存档将使会话处于非活动状态。恢复更改会话记录；它不撤销文件。Claude公开压缩和分叉，而归档和会话恢复报告为不支持。 使用 `account --provider ` 对于安全的本地帐户元数据，和 `mcp-servers --thread-id ` 查看已配置的服务器状态。 `mcp-tools` 和 `mcp-resources` 选择 `--server-name ` 并且支持有界延拓。本机重新加载和身份验证控件使用现有的JSON `request` 接口和持久操作收据。登录url是实时呈现的，永远不会保存在SQLite中。看到 [本地帐户和扩展](https://npmcn.com/package/jg-agent-hq/api/README.md#native-accounts-and-extensions)。 使用 `models --provider ` 对于本地模型和工作选择，和 `configuration --provider --workspace-root [--thread-id ]` 对于已知的有效设置和分页本机代理/配置文件元数据。创建和显式恢复接受键入的启动设置；消息可以为下一个回合选择一个模型和工作。启动指令、本机Claude代理和权限设置需要空闲会话重新启动。能力模式描述支持的选择和更改模式。未知的设置仍然是显式的，本地配置文件保留在每个CLI中。看到 [配置合同](https://npmcn.com/package/jg-agent-hq/api/README.md#native-configuration)。 本地执行设置、指令、技能和工具权限保留在每个CLI中。Claude在每个受控会话中使用自己的结构化进程，在空闲60分钟后关闭它，并在下一次输入时重新打开它，并使用结构化用户消息来引导其活动回合。在确认采用、恢复或恢复之前关闭其他CLI控制器。总部协调共享一个状态目录的会话；它不能锁定独立运行的本机cli。 集成浏览器主机可以通过编程API使用持久的主机-操作许可和操作符范围的协调；看到 [浏览器主机契约](https://npmcn.com/package/jg-agent-hq/api/README.md#browser-host-integration)． 独立的CLI只发布它实现的命令。 审批读取在重新连接或重新启动后返回索引的、游标分页的挂起、应答的和过期的元数据。敏感表示仅在准确的本机请求存在时可用。本地权限需要显式响应；未知的请求类型或范围被拒绝。看到 [本地回复和重新连接读取](https://npmcn.com/package/jg-agent-hq/api/README.md#thread-control-and-live-input)。 持久状态包括 `action.key`，它必须保持私有，并与其SQLite数据库一起使用。保存排队的未交付输入和完整的有界最终结果；普通的输入主体和问答则不是。 文本和技能输入可以根据路径和媒体类型附加多达8个工作空间文件，总共16 MiB，每个文本文件256 KiB。HQ在排队交付之前再次验证它们的内容哈希值。输出模式使用原生Codex回合参数或Claude的结构化会话标志；重新连接后，所选收据上的完整验证结果和已知令牌使用情况仍然可用。实时预览保持有界并显式标记截断。看到 [文件输入和完成结果](https://npmcn.com/package/jg-agent-hq/api/README.md#file-inputs-and-complete-results)。 使用 `suggest-thread-name --topic "Build usage" --state-root ` 用于可编辑标签和 `managed-thread-name --name build-usage --state-root ` 来解决它。当名称被占用时，“创建”将添加一个简短的序号后缀。操作和关系保留不可变的id。 使用 `skills --workspace-root --state-root ` 要浏览本机技能目录，在该文件夹中启动的会话将具有 `--provider` (默认 `codex`)，并添加 `--thread-id ` 用于受控会话自己的目录。 `skill-preview --thread-id --skill-id --arguments "auto exact-plan" --state-root ` 显示准确的调用而不发送它。缺失的本机元数据显式不可用。CLI加载所有技能内容，并保留其权限和调用规则。 使用 `jg-agent-hq request --state-root ` 在stdin上有一个封闭的HQ命令，用于操作和控制读取。这个 [API参考](https://npmcn.com/package/jg-agent-hq/api/README.md) 描述动作信封、收据和重新连接读取。 ## 源的例子 遵循 [完成会话演练](https://jg-agent-hq.jesusgraterol.dev/examples/)，并提供可复制的来源及其结果。 `examples/control-session.ts` 创建一个本机会话并读取其实际交付、输出、许可和使用观察。 这些完整的TypeScript示例使用了公共客户端和契约。启动本地控制器并首先登录到本机cli。主机提供实际的用户决策，并保持本地权限处理独立。在提交请求前保留请求的身份；在中断客户端呼叫后，检查这些收据，而不是重新运行整个示例。例如开发源，而不是包导出或自动网站操作。 `examples/shared-storage.ts` 使用受信任的Node运行时在app\_前缀下保存单个应用程序首选项，捕获和检查共享SQLite存储，并在离线恢复后验证值。它关闭自己的SQL连接并保留主机的user\_version。选择不存在的输出目录，并首先暂停所有其他写入器。应用程序在捕获前写提交；以后的备份失败不会回滚。恢复的状态在执行之前仍然需要显式的允许根。 这个 [资格矩阵](https://npmcn.com/package/jg-agent-hq/api/README.md#qualification) 记录本机行程、主机覆盖范围和剩余接口限制。 ## 项目蓝图 - `src/index.ts`：显式的公共包边界。 - `examples/`：用于会话和共享主机存储的公共源代码助手。 - `src/locks/`：锁的所有权、获取、状态和有意恢复。 - `src/runtime/`：可信配置和终身所有权。 - `src/ipc/` 和 `src/cli/`：私有本地命令和已安装的可执行文件。 - `src/providers/codex/`：共享的应用服务器守护进程连接、本地历史记录和帐户协议。 - `src/providers/claude/`：本机结构化控制和使用，身份验证，工作人员拥有的本地历史阅读器，活动会话轮询和后台任务计数器，它读取成绩单。 - `src/providers/registry/`惰性工厂、规范化的提供者证据、有界生命周期和源隔离。 - `src/providers/inputs/` 和 `src/providers/results/`：检查文件交付和完成本机结果验证。 - `src/providers/configuration/` 和 `src/providers/lineage/`有限的本地选择和确定的不可变会话关系。 - `src/sessions/`：具有实时会话状态、活动会话列表、有界证据和来源、游标绑定历史读取和短标签建议的授权发现。 - `src/skills/`：有界本地编目、调用预览和显式输入准备。 - `src/accounts/` 和 `src/extensions/`：安全的账户观察和授权，有界的本地MCP库存。 - `src/actions/`：持久的动作调度，本地输入路由，有界的实时表示和接收等待自己的变化唤醒。 - `src/store/`SQLite发现元数据，观察到的会话和状态转换，动作/控制分类帐和快照的数据库副本在一个worker中。 - `src/storage/`：可信主机元数据、独占维护和当前模式戳。 - `src/snapshots/`：在代理工作时捕获，清单验证和释放本机所有权的离线恢复。 - `src/contracts/`浏览器安全的命令和响应契约，包括jg-locks锁列表。 - `scripts/package/`：构建输出清理和打包消费者检查。 - `scripts/release/`：注册表版本/完整性检查和测试存档的可信发布。 - `scripts/test-support/`：一次性外部CLI固定装置。 - `vitest/`：分离单元和集成选择。 - `api/README.md`：规范的公共API引用。 - `errors/README.md`：稳定应用错误。 - `website/`：私有的公共站点工作区，带有自己的README和测试/检查命令；规范文档主体保留在这个根README和 `api/README.md`。 - `docs/website.md`：持久的网站架构，验证和生成的资产来源。 - `docs/architecture.md`：提供程序和数据库所有权、模式初始化和主机维护。 - `docs/recovery.md`：本地快照覆盖，离线恢复和主机的远程持久性责任。 `/docs` 保留用于简洁，快速扫描的基本持久概念和过程的文档。API引用保持在外部 `/docs`。 ## 测试 测试使用构建的公共输出。单元测试涵盖应用程序拥有的决策；集成测试使用真正的临时文件、SQLite工作线程、IPC、子进程和一个孤立的tarball消费者。合成的cli只替换外部提供者边界。每个fixture移除自己的资源。生产输出排除所有测试类别。 `pnpm test` 构建，然后运行单元和集成套件。 `pnpm check:package` 是任务完成检查。使用Vitest's连续运行更改的集成文件三次，禁用重试 `--repeats=2 --retry=0`。 该网站的README和 `docs/website.md` 定义它的一次构建检查组合、特定于类别的脚本和拥有的预览/浏览器生命周期。当工作空间配置或规范站点内容发生更改时，必须同时通过根检查和网站检查以完成任务。 运行时fixture拆卸会向测试运行器和回调程序注册，因此测试超时不能在下一个测试期间恢复环境变量。 当前本地检查仅建立被测试的主机。发布资格必须包括Node引擎层和当前LTS；macOS操作需要自己的运行时证据。 ## 常见问题 ### jg-agent-hq 是什么？ 本地Claude Code和Codex会话控制，历史，使用和可恢复的本地存储为Node\.js应用。 ### 如何安装 jg-agent-hq？ 在项目目录运行 npm install jg-agent-hq，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 jg-agent-hq，可以用 npx jg-agent-hq 直接运行。 ### jg-agent-hq 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### jg-agent-hq 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### jg-agent-hq 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=24\.15\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### jg-agent-hq 可以商用吗？ jg-agent-hq 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### jg-agent-hq 还在维护吗？ 最新版本 11\.1\.0 发布于 2026/11/04（1 天前）；至今共发布 45 个版本，其中过去 12 个月发布了 45 个；首次发布于 2026/10/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。