# @agentskit/harness 中文文档

规范地址：https://npmcn.com/package/%40agentskit/harness/

版本：0\.22\.3
npm 元数据更新时间：2026-09-27T18:09:48.882Z
中文译文更新时间：2026-11-05T22:44:12.058Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agentskit/harness
原文对照：https://npmcn.com/package/%40agentskit/harness/?lang=original
项目主页：https://github.com/AgentsKit-io/harness
源码仓库：https://github.com/AgentsKit-io/harness

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

- 包体积（解压后）：9.3 MB，76 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：6 个
- 首次发布：2026-08-31T15:44:34.882Z
- 最新版本发布：2026-09-27T18:09:48.549Z
- 近 30 天下载量：10976（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

可移植,有证据支持的编码剂开发利用.

## 安装

```sh
npm install @agentskit/harness
```

也可以使用：`pnpm add @agentskit/harness`、`yarn add @agentskit/harness`、`bun add @agentskit/harness`

## README

* * *

## 道克桥: 涵盖: - 软件包:@agentskit/harness

# @ agentskit/ 痛苦

**你SDLC的循环.** 一个模糊的目标变成PRD,PRD变成问题,每个问题 成为一份被冻结的合同,一个工人在自己的工作树上,一个经过审查的拉动请求被证明符合以下定义: 完成合并,在人门后释放.

本地 UI 是可选和回回保护的: 它工程 `.ak-loop/` 文档和事件,并可以不添加守护进程或数据库而开始输入Harness任务。 其主要流程是第一问题:选择一个现有问题,冻结其合同/简介/限制,将其排入其中,并仅从持久的收件箱中解决人类的决定. 文档 : **[agentskit.io (英语)](https://harness.agentskit.io/)**

## 安装

```bash
pnpm add -D @agentskit/harness     # Node 22+
```

节点22或更新. 两个二进制 : `ak-harness` (每样东西)和 `ak-verify` (常见下相同的二进制) 校验-校正名称).

## 60秒钟

```bash
npx ak-harness loop init           # writes loop.config.yaml from a preset
npx ak-harness loop doctor         # providers, routing, slots, queue — dispatches nothing
npx ak-harness ui                  # local operational view at http://127.0.0.1:4321
npx ak-harness loop tick --dry-run --max 1
npx ak-harness loop install        # puts tick + deliver on a schedule
```

然后,它运行没有你: `tick` 合同和发货, `deliver` 驱动拉动请求合并 .

## 跑步的样子

```console
$ ak-harness loop tick --max 1
{"status":"ok","routing":{"orchestrator":"codex/gpt-5.6-sol","builder":"codex/gpt-5.6-luna"},
 "results":[{"issue":"REP-141","outcome":"dispatched","branch":"you/rep-141-usage-flag",
             "worktree":"rep-141-usage-flag","contractDigest":"9f2c1ab4…"}]}

$ ak-harness loop deliver
{"results":[{"issue":"REP-141","outcome":"fix-round","pr":482,
             "reason":"review found 2 blocking finding(s)"}]}

$ ak-harness loop deliver
{"results":[{"issue":"REP-141","outcome":"merged","pr":482,
             "actions":["local verify passed before review","verify.json supplied 2 outcome proof(s)",
                        "definition of done proven (5 item(s))"]}]}
```

## 工人留下证据,而不是承诺

3个文件 `.ak-loop/` 在它的根 工作树. `deliver` 在合并门前读取; 缺少 一只像圆形一样回来 **命名文件**。 。 。 .

```jsonc
// .ak-loop/verify.json — what it ran, outcome by outcome
{ "ranAt": "2026-09-20T18:04:11.000Z", "command": "pnpm test packages/report", "exitCode": 0,
  "outcomes": [{ "id": "o1", "status": "passed", "evidence": "42 passed | 0 failed" }] }
```

```jsonc
// .ak-loop/dod.json — both definition-of-done lists
{ "project":  [{ "id": "tests", "status": "passed", "evidence": "212 tests · 212 pass" }],
  "outcomes": [{ "id": "o1",    "status": "passed", "evidence": "returns 404 for an unknown id" }] }
```

`.ak-loop/plan.md` 第三个是:工人实际遵循的计划,该计划偏离了批准的计划 一个.

## 配置, 按实例

```yaml
# loop.config.yaml — the project's layer (there are four; the project outweighs the global one)
project: { name: report, repo: acme/report, baseBranch: main }
delivery:
  verifyCommand: pnpm lint && pnpm test
  review: { minSeverity: med, votes: 1 }
  merge: { auto: true, requireChecks: true }
```

```yaml
# Every issue must prove the project's list, on top of its own contract outcomes.
dod:
  items:
    - { id: tests, description: the suite is green, kind: command, command: [pnpm, test] }
    - { id: changelog, description: the changelog moved, kind: file-changed, glob: CHANGELOG.md }
```

```yaml
# One motor, three kinds of demand. A pin narrows the candidates; it never widens them.
flows:
  default: standard
  profiles:
    standard: { review: { votes: 1, minSeverity: med } }
    critical:
      review: { votes: 3, minSeverity: nit }
      merge: { requireHumanApproval: true }
      roles: { review: { provider: codex, model: gpt-5.6-sol, effort: xhigh } }
    incident:
      merge: { requireChecks: false }
      stages: { planner: false, vote: false, review: false }
      maxFixRounds: 1
  select:
    - { flow: incident, anyLabels: [sev1] }
    - { flow: critical, anyLabels: ['area:billing'] }
```

```yaml
# A layer says which test closes an issue — cheaper than the whole suite on a monorepo.
layers:
  - { id: L2, label: 'layer:L2', paths: ['packages/runtime/**'], verify: pnpm test packages/runtime }
```

### GitHub 问题作为已配置的跟踪器

当 UI 和执行环路运行于 GitHub 时, 设置跟踪器到 GitHub `project.repo`数字 :

```yaml
connectors:
  tracker: github
github:
  issues:
    state: open
    maxIssues: 500
    refreshSeconds: 60
    labels:
      todo: loop:todo
      inProgress: loop:in-progress
      review: loop:review
      done: loop:done
      blocked: loop:blocked
```

机智称现有 `gh` CLI, 按最近更新的排序, 缓存棋盘于 `.ak-loop/ui/github-issues.json`。 。 。 . `gh auth status` 和寄存器写入权限在变异任务之前检查. 生命周期标签是专属的; `done` 关闭一个问题, 活动状态重新打开它 。 缺少配置标签失败 关闭。 UI 曝光已打入,确认的动作和任务;每个配置只选择一个跟踪器.

谐音读取 `loop.config.yaml`;它不消耗项目 `.github/ai-loop.yaml`,其计划属于 不同的执行者.

## 图标

| 只读 |  |
| --- | --- |
| `loop doctor` | 提供商、用户、线路、插槽、选定跟踪板、安装代理 |
| `loop debrief` | 现在的循环是做什么的,每期 |
| `loop observe --since 24h` | 异常和衡量标准; `--precheck` 给出调度器退出代码 |
| `loop retro --since 7d` | 文摘、学习和校准建议 |
| `loop status` • 妇女 `loop watch --once` • 妇女 `loop paused` | 飞行中停止的飞行阶段时间表 |

| 行为 |  |
| --- | --- |
| `loop tick` • 妇女 `loop deliver` | 发车证 发车证 发车证 `--dry-run`(中文(简体) ) |
| `loop plan start | answer | approve | architect | approve-design | decompose` | 目标-PRD-设计-问题-两个人行门 |
| `loop release status | approve | run` | 推动一个批量的人类批准, 捆绑在一头sha |
| `loop install` • 妇女 `loop uninstall` • 妇女 `loop resume` | 调度,并清除暂停 |

## 作为图书馆

```ts
import { loadLoopConfig, resolveFlowSettings, assessDod, readPhaseArtifacts } from '@agentskit/harness'

const { config } = loadLoopConfig('loop.config.yaml')
const flow = resolveFlowSettings(config, { labels: ['sev1'] })
// → flow.review.votes, flow.merge.requireChecks, flow.flow.name === 'incident'

const artifacts = readPhaseArtifacts('/path/to/worktree', config)
// → [{ name: 'verify', file: '.ak-loop/verify.json', present: true, valid: true, detail: '2 outcome(s)' }, …]
```

```js
// plugin.mjs, declared in `plugins.modules` — a gate of your own
export default function register(bus) {
  bus.on('pr.merged', (event) => metrics.count('merged', event.issue))
  bus.hook('beforeMerge', ({ issue }) => isChangeFreeze() ? { block: true, reason: `freeze: ${issue}` } : undefined)
}
```

## 此外:核查议定书

同样的二进制运行循环构建的单运行协议——被冻结的合同,可执行检查绑定 以及一项明确的人类决定:

```bash
ak-harness plan approved --by human
ak-harness start
ak-verify run --json
ak-verify approve approved --by human --json
```

```json
{"status":"passed","criteria":["api-behavior"]}
```

每张支票的最终输出线是JSON映射到它所证明的结果ID. 证据与罪犯有关 图形 `HEAD`; 任何源、配置或合同更改将运行移动到 `STALE`。运行后附加一个散列链 `events.ndjson` - 核查一个 `ak-harness events verify [run-id]`。 。 。 .

可运行实例 : [`examples/minimum-profile.mjs`](https://npmcn.com/package/%40agentskit/harness/examples/minimum-profile.mjs) (之后) (中文(简体) ) `pnpm build`) (中文(简体) ).

## 再来

-   **[agentskit.io (英语)](https://harness.agentskit.io/)** 概念、指南、实例和生成的 用于每个配置路径、命令和事件的引用.
-   [文件/已安装](https://npmcn.com/package/%40agentskit/harness/docs/GETTING-STARTED.md) • 妇女 [文件/记录](https://npmcn.com/package/%40agentskit/harness/docs/TROUBLESHOOTING.md) • 妇女 [文件/记录和记录](https://npmcn.com/package/%40agentskit/harness/docs/LOOP.md)
-   决定: [ADR-0027 (英语)](https://npmcn.com/package/%40agentskit/harness/docs/ADR-0027-keep-pushing-loop.md) (循环).. [ADR-0032 (英语)](https://npmcn.com/package/%40agentskit/harness/docs/ADR-0032-loop-stages-as-state-machines.md) (阶段) [AR-0035 (英语)](https://npmcn.com/package/%40agentskit/harness/docs/ADR-0035-definition-of-done-two-lists.md) · (已完成的定义) [ADR-0037 (英语)](https://npmcn.com/package/%40agentskit/harness/docs/ADR-0037-cost-policy-ceilings-and-levers.md) (费用)
-   [捐款额](https://npmcn.com/package/%40agentskit/harness/CONTRIBUTING.md) • 妇女 [变动情况](https://npmcn.com/package/%40agentskit/harness/CHANGELOG.md) • 妇女 [MANIFESTO.MD 马里福尔大学](https://npmcn.com/package/%40agentskit/harness/MANIFESTO.md)

## 释放

这个 `publish` 任务在 [`.github/workflows/release-harness.yml`](https://npmcn.com/package/%40agentskit/harness/.github/workflows/release-harness.yml) 在合并时发布到 `main`, (中文(简体) ), 通过 npm 信任的出版( GitHub OIDC) — no `NPM_TOKEN` 随便哪里 它和它的工作流程一样 检查和 `needs` 每一个,所以一个承诺不能通过红门发布;一个版本还没有在 登记册是触发器。 文件有支票和出版物: npm 信任的出版授权 数据库和工作流程 **文件名**,因此将它重新命名为断开放出,直到npm设置匹配。 这个 候选清单和任何开放的阻塞器 [`release/manifest.json`](https://npmcn.com/package/%40agentskit/harness/release/manifest.json) 财务报告和审定财务报表 [`release/notes.md`](https://npmcn.com/package/%40agentskit/harness/release/notes.md)。 。 。 .

麻省理工学院下属的自由开放源代码. 见 [自由主义](https://npmcn.com/package/%40agentskit/harness/LICENSE)。 。 。 .

## 探员 Kit 生态系统

-   [探员Kit](https://www.agentskit.io/)
-   [书记官处](https://registry.agentskit.io/)
-   [聊天](https://chat.agentskit.io/)
-   [多克桥](https://doc-bridge.agentskit.io/)
-   [代码审查](https://code-review.agentskit.io/)
-   [节奏](https://harness.agentskit.io/)

## 常见问题

### @agentskit/harness 是什么？

可移植,有证据支持的编码剂开发利用\.

### 如何安装 @agentskit/harness？

在项目目录运行 npm install @agentskit/harness，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ak-verify、ak-harness，可以用 npx ak-verify 直接运行。

### @agentskit/harness 支持 TypeScript 吗？

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

### @agentskit/harness 支持 ESM 还是 CommonJS？

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

### @agentskit/harness 需要什么版本的 Node\.js？

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

### @agentskit/harness 可以商用吗？

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

### @agentskit/harness 的下载量有多少？

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

### @agentskit/harness 还在维护吗？

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