# harnery 中文文档

规范地址：https://npmcn.com/package/harnery/

版本：0\.48\.0
npm 元数据更新时间：2026-11-03T18:52:06.995Z
中文译文更新时间：2026-11-03T20:09:58.256Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/harnery
原文对照：https://npmcn.com/package/harnery/?lang=original
项目主页：https://harnery.com/
源码仓库：https://github.com/ryanjkelly/harnery

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

- 包体积（解压后）：17.9 MB，2357 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：15 个
- 首次发布：2026-06-20T11:03:32.356Z
- 最新版本发布：2026-11-03T18:52:06.601Z
- 已发布版本数：67（近 12 个月 67 个）

## 中文简介

人工智能编码代理的多代理协调- Claude Code， Cursor和Codex。

## 安装

```sh
npm install harnery
```

也可以使用：`pnpm add harnery`、`yarn add harnery`、`bun add harnery`

## README

![Harnery](https://npmcn.com/package/harnery/assets/harnery-logo-transparent.svg)

# Harnery

> 人工智能编码代理的多代理协调：Claude Code， Cursor和Codex。

[![CI](https://github.com/ryanjkelly/harnery/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanjkelly/harnery/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/harnery.svg)](https://www.npmjs.com/package/harnery) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://npmcn.com/package/harnery/LICENSE)

> ⚠️ **pre - 1.0。** API表面仍在沉淀。固定一个特定的次要版本(`harnery@^0.31.0`)，并阅读 [更新日志](https://npmcn.com/package/harnery/CHANGELOG.md) 每次升级前。

## 它是什么？

`harnery` 防止多个AI编码代理在共享签出时踩到对方。它来自于多年来同时运行几个Claude Code / Cursor / Codex会议来对抗同一个单变量。

-   **多智能体协调。** 每个代理心跳 `.harnery/active/`、声明时间和提交时间守卫、规范事件流、理事会、决策摘要、每个代理的日志，以及用于Claude Code / Cursor / Codex的适配器适配器。
-   **跨机器的存在。** 共享一个仓库的每台机器上的会话都可以看到对方，并按机器标记。在repo自己的git远程（存在参考）上进行零配置，并通过端到端加密中继进行可选的live-socket升级：public `relay.harnery.com`，或自我主持 `harn relay serve` /捆绑的Cloudflare Worker (`relay/worker/`）. 中继只能看到命名不透明的房间里的密文。
-   **Coordination-aware工作流。** `harn run <script>` 运行有界的、模式控制的多子代理工作流脚本。纯JS阶段呈扇状分布到无头适配器- cli子代理，这些子代理是协调注册的（心跳、事件、索赔保护），确定性代码决定阶段之间的路由。一个可选的主机拥有的策略将调度和声明的外部突变与 `ALLOW`， `ASK`, `DENY`． CLI `ASK` 对于明确的批准/拒绝和同运行恢复，请求持久地停放；默认情况下，库调用者保持失败关闭状态。
-   **可选的隔离工作区。** 添加 `--isolation worktree --workspace-root <dir>` 在主机拥有的本地Git工作树中运行工作流。Harnery冻结分配和提供者标识，在执行和恢复之前验证工作空间，在快速集成之前需要审查和策略权限，并保持保守的清理。检查与 `harn run workspace`，然后使用分开的 `run integration prepare`， `integration apply`, `cleanup` 阶段。共享执行仍然是默认的。
-   **持久工作高于尝试。** `harn work` 在有界的工作流尝试、依赖项、批准暂停、失败和审查中保持目标的活力。可重用工作流代码接收作为冻结类型上下文的确切工作ID、标题、目标、验收标准和尝试标识。重试还接收到先前运行的有界错误和未解决的证明标准；重试权限和尝试上限保持不变。 清单、证明和仅追加的分类账绑定相同的上下文，一次性协调器报告下一个显式操作，而不需要静默地生成、重试或接受工作。
-   **有界目标监督。** `harn governor` 冻结任务或现有的根图、专家团队和安全限制，然后运行调度周期，直到审查任务成功、人员注意、没有进展或预算耗尽。它的可选计划器可以创建第一个里程碑，重新评估已接受的里程碑证明，或者仅使用冻结的工作流模板目录恢复终端图。在普通批准或自动申请授权之前，计划可能需要独立的有限专家审查。 老一代保持不变的证据，所有的尝试仍然消耗目标预算。在可选的心跳后台服务中使用显式前台标记或注册目标。
-   **独立的web UI。** `harn web up` 为代码层启动一个本地Next.js仪表板、理事会、每个项目状态和一个本地编码代理状态视图(Claude Code / Codex / Cursor使用情况，由 `harn devtools`）. 附带的是git克隆包，而不是npm包(参见 [安装](https://npmcn.com/package/harnery/#readme-install)）.
-   **备份+同步。** `harn backup` 快照 `.harnery/` 通过 [化通体](https://restic.net/)； `harn sync` 通过使一个精心策划的子集跨机器存活 [rclone](https://rclone.org/) （谷歌驱动器或任何克隆远程）。

CLI还附带电池：便携式实用程序命令(`tokens`， `eml`， `env`， `grep` 对于并行的，ripgrep加速的单点搜索，加上 `docs`， `browse`， `fetch`， `read`， `webview`， `devtools`以及它们赖以构建的库工具包。默认情况下，每个页面加载器都以人的速度读取，通过机器范围的分类账在一个站点的加载之间等待3到9秒 `--no-pace` 和 `HARNERY_PACE=off` 选择退出。有用的，跨平台的，轻依赖的，但故意不是标题。协调是和谐存在的原因；工具包的存在是因为CLI需要它(参见 [公共表面层](https://npmcn.com/package/harnery/#readme-public-surface-tiers)）.

## 安装

```bash
curl -fsSL https://harnery.com/install.sh | bash
```

一行，没有克隆：它安装 `harn` 全局CLI（首选npm， Bun backback），把它放在你的 `PATH`，并进行验证。或者直接驱动包管理器： `npm install -g harnery` / `bun add -g harnery` (或 `npm install harnery` 对于一个项目部)。然后连接一个项目：

```bash
harn init     # creates .harnery/ + registers the adapter hooks
harn doctor   # optional: one-time runtime + dependency check
```

> **从git克隆？** 克隆 `web/` 仪表板还是贡献？ `./scripts/setup.sh` 克隆安装是否一次完成：安装deps，构建 `dist/` 运行 `harn init`，并将箱子连接到你的 `PATH`。

> **npm给你引擎+ CLI。** 这个 `web/` 仪表盘和 `docs/` 站点位于git仓库中，而不是npm包（它是CLI +代码引擎）： `bin`， `dist`， `src`， `schemas`）. 要运行仪表板， `git clone` 回购, `bun install`, `harn web up` 从那里，指向你的项目 `--coord-root <dir>` （或者只是在项目内部运行它）。 `harn web up` 如果在没有克隆存在的情况下调用它，则打印这些确切的步骤。

### 本机Windows源代码签出

对于Windows上的源代码开发，安装Node.js 20.19+和Bun，然后使用 PowerShell 7:

```powershell
bun install --frozen-lockfile
Push-Location web
bun install --frozen-lockfile
Pop-Location
npm link --ignore-scripts --offline --package-lock=false
harn init --project-root 'C:\path\to\project' --adapter 'claude-code,codex'
harn web up --coord-root 'C:\path\to\project'
```

这个 [本机发射器](https://npmcn.com/package/harnery/bin/README.md) 通过Bun运行源代码，不需要Bash。 仪表板与环回绑定。法典钩子命令仍然需要脊甲 在新的会话可以执行它们之前进行单独的审批。

Windows状态继承NTFS acl: POSIX模式位不能证明这些访问 的权利。在发布之前仍然刷新文件内容；Windows没有 支持用于POSIX目录条目持久性的目录fsync。原子 文件发布和租赁所有权检查仍然存在。

## 卸载

两层。 **解除项目连接** (使 `.harnery/` 默认为历史记录；在终端上，它在删除它之前会询问：

```bash
harn deinit                 # unwire the adapter hooks
harn deinit --purge-state   # also delete .harnery/ (destructive)
```

**移除命令行** 使用托管的一行程序(`npm rm -g harnery` / `bun remove -g harnery` 工作):

```bash
curl -fsSL https://harnery.com/uninstall.sh | bash
```

从git克隆， `./scripts/teardown.sh` 是我的镜子 `./scripts/setup.sh`：它运行。 `harn deinit`，移除 `PATH` 和（在终端上）询问是否也删除这个项目的 `.harnery/` 历史和克隆本身。两者默认为no；pre-answer与 `--purge-state` 和 `--remove-clone` 对于无人看管的运行。

## 用作CLI库

特定于项目的cli组成Harnery的命令树，并在上面添加自己的命令：

```ts
// mycli/src/program.ts
import { createHarneryProgram } from 'harnery/commander';
import { deployCommand, dbCommand } from './commands';

const program = createHarneryProgram({
  binName: 'mycli',
  context: { projectName: 'my-monorepo' },
});

program.addCommand(deployCommand);
program.addCommand(dbCommand);

await program.parseAsync(process.argv);
```

`mycli agents status` 然后决定 **同样的代码** 作为 `harn agents status`，作为库加载。看到 [例子/ extending-with-commander.ts](https://npmcn.com/package/harnery/examples/extending-with-commander.ts) 完整的模式。

### 公共表面层

出口映射在什么是和谐之间画了一条线 _是_ 它是什么？ _附带_：

-   **产品层** （`harnery`， `harnery/commander`， `harnery/core/*`)：协调层和CLI组成。这是要构建的API，也是安装harnery的原因。
-   **工具层** (每 `harnery/lib/*` 子路径: `http`， `cookies`， `format`， `readability`， `browser`， `machine`（…）：harnery自己的CLI构建的支持实用程序，为想要依赖它们的嵌入主机公开。支持，但次要的：它可以比产品层发展得更快，并且它不是单独采用harnery的理由。

边界是强制的，而不是期望的：CI验证否 `harnery/lib/*` Export直接或传递地导入协调核心(`scripts/check-layering.ts`)，因此拖拽工具箱模块永远不会拖拽到协调状态。细节: [嵌入+表面分层](https://harnery.com/concepts/embedding/)。

## 文档

完整文件载于 **[harnery.com](https://harnery.com/)**：

-   [开始](https://harnery.com/getting-started/install)
-   [特性](https://harnery.com/features/session-state/)
-   [指南](https://harnery.com/guides/manage-claude-desktop-sessions/)
-   [CLI参考](https://harnery.com/cli/)
-   [概念](https://harnery.com/concepts/coord-layer)
-   [配置模式](https://harnery.com/reference/config-schema)

## 贡献

看到 [CONTRIBUTING.md](https://npmcn.com/package/harnery/CONTRIBUTING.md)． Bug报告和特性请求通过 [GitHub的问题](https://github.com/ryanjkelly/harnery/issues)。

## 许可证

[麻省理工学院](https://npmcn.com/package/harnery/LICENSE) ©Ryan Kelly

## 常见问题

### harnery 是什么？

人工智能编码代理的多代理协调- Claude Code， Cursor和Codex。

### 如何安装 harnery？

在项目目录运行 npm install harnery，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 harn、agent-hook、agent-coord，可以用 npx harn 直接运行。

### harnery 支持 TypeScript 吗？

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

### harnery 支持 ESM 还是 CommonJS？

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

### harnery 需要什么版本的 Node\.js？

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

### harnery 可以商用吗？

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

### harnery 还在维护吗？

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