# @archmax-ai/harness 中文文档

规范地址：https://npmcn.com/package/%40archmax-ai/harness/

版本：2\.0\.1
npm 元数据更新时间：2026-11-03T12:43:13.765Z
中文译文更新时间：2026-11-06T14:36:10.594Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.6 MB，393 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：13 个
- 首次发布：2026-09-24T07:56:55.753Z
- 最新版本发布：2026-11-03T12:43:13.002Z
- 近 30 天下载量：5530（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

特工们无法可靠地遵循程序 亚克马克斯的拉带让他们: 在LangChain Deep Agents之上的规范层 在每个步骤上执行一个宣告性的工作流程状态机器.

## 安装

```sh
npm install @archmax-ai/harness
```

也可以使用：`pnpm add @archmax-ai/harness`、`yarn add @archmax-ai/harness`、`bun add @archmax-ai/harness`

## README

# 拱顶吊带

**一层薄薄的,有管理的地层 [朗彩深处 探员](https://docs.langchain.com/oss/javascript/deepagents/overview)。每次会议都运行 在一个声明性工作流程状态的机器下,您在一个YAML文件中写作.**

## 为何要用拱顶吊带

与AI代理的可靠自动化应该跟随这个过程,拥有该程序的人应该 进程应该能够编写。 今天,大多数域专家都无法做到这一点. 目前的自动化工具在三个方面都不足.

-   **代理人是一个步骤,而不是过程.** 经纪人坐在一个固定的图里 所以 灵活性结束于一个节点的边缘。 过程和图表一样僵硬 画了.
-   **这一进程及其执行是分散的.** 每一个业务流程均重报为 技术图。 使两件艺术品和两个主人 永远保持同步 停止成本计算.
-   **复杂数据仍以代码结尾.** 编码中的嵌入式有效载荷、环和算术用地 节点。 拥有这一过程的人不能读取,更不要说修改了.

拱顶吊带扭转了局面 经纪人负责整个过程,一个 `workflow.yaml` 两者 描述并强制执行它。 数据工作在沙盒里发生 同样的规则.

**完整文档: [https://harness.archmax.ai/ (中文(简体) )](https://harness.archmax.ai/)**

## 安装

```bash
npm install @archmax-ai/harness
```

节点22或后. 该模型是通过环境配置的,与任何 OpenAI 兼容 终点 拱顶吊带读取这些钥匙 `.env` 工作空间根 :

```bash
ARCHMAX_API_BASE_URL=https://api.example.com/v1
ARCHMAX_API_KEY=...
ARCHMAX_MODEL=...
```

`ARCHMAX_MODEL` 默认值。 一个工作流程名称 ID 状态运行 `settings.model`, (中文(简体) ), 并且一个州会用它自己的 `model:`无论如何,它是一个身份,解决了 同样的终点和证书。 所以机械状态可以运行在小模型上 而状态 一个人读的输出 运行在一个能力.

见 [配置](https://harness.archmax.ai/reference/configuration/) 页:1 每个变量.

要为您设置一个编码代理( Claude Code, Cursor, Codex,...) 作者工作流程, 安装 编写技能 :

```bash
npx skills add archmax-ai/harness
```

## 快速启动

四个州的退款台 代理决定退款 并起草电子邮件,脚本检查 反政策的决定, 一个分级员检查电子邮件, 代理发送它。 完整 实例在 [`examples/refund/`](https://npmcn.com/package/%40archmax-ai/harness/examples/refund/)。 。 。 .

```
refund/
├── index.js                          # your program: the host tools and the agent
├── tools.js
└── workflows/refund/
    ├── workflow.yaml                 # the process, enforced
    └── scripts/check-decision.js     # the deterministic check
```

### 工作流程

```yaml
# workflows/refund/workflow.yaml
title: Refund request
instructions: Decide only from what lookup_customer returns; never guess an order.

states:
  decide:
    triggers:
      manual:
        requires: [email]
    tools:
      allow: [lookup_customer]
    instructions: >-
      Look the customer up with lookup_customer, using the `email` variable. A
      refund is approved only when their order is delivered; otherwise it is
      denied. Record the decision with archmax_set_variables as `decision`
      (approved or denied), write the email to the customer in
      scratchpad/email.md, then advance to check-decision. If you are sent
      back, fix what the note says and advance again.
    transitions:
      - to: check-decision
        description: The decision is recorded and the email is drafted.

  check-decision:
    type: code
    script: scripts/check-decision.js
    tools:
      allow: [lookup_customer]
    transitions:
      - to: review-email
        description: The decision matches the refund policy.
      - to: decide
        description: The decision contradicts the refund policy.

  review-email:
    type: grader
    instructions: >-
      Read scratchpad/email.md and the `decision` variable. Approve the email
      when it is polite, states the decision plainly and names the order.
      Otherwise send it back, saying exactly what to change.
    transitions:
      - to: send
        description: The email is ready to send.
      - to: decide
        description: The email needs changes.

  send:
    tools:
      allow: [send_email]
    instructions: >-
      Send scratchpad/email.md to the customer at `email` with send_email, then
      say in one sentence that it was sent.
```

每个状态都是过程的一步,而代理人只看到它所在的一步: 状态的指令,其工具和其中的转换, 每一个描述,以便它可以选择 他们之间 它通过呼叫继续前进 `archmax_advance`,而运行时间拒绝任何边缘 状态没有 声明 无过渡状态,如 `send`,是会议结束的地方.

其中两个州没有代理运营. **`check-decision` 是一个代码状态**: 运行时间 它的脚本进入, 没有模式调用. **`review-email` 是一个分级状态**: 一个孤立的 代理根据州政府的指示判断电子邮件。 两个都只到达自己的州 工具, 双方决定 同样的代理方式,与 `archmax_advance`返回到 代理作为笔记 它读之前再次尝试.

### 检查

```js
// workflows/refund/scripts/check-decision.js
/** A refund is due only for a delivered order: any other decision goes back to the agent. */
export default async function ({ variables, tools }) {
  const customer = JSON.parse(await tools.lookup_customer({ email: variables.email }));
  const order = customer?.order;
  const due = order?.status === "delivered" ? "approved" : "denied";

  if (variables.decision === due) {
    await tools.archmax_advance({
      to: "review-email",
      reason: `The refund is ${due}, as the policy requires.`,
    });
  } else {
    await tools.archmax_advance({
      to: "decide",
      reason: `Order ${order?.id ?? "(none)"} is ${order?.status ?? "unknown"}, so the refund must be ${due}.`,
    });
  }
}
```

政策是建立在代码上的 所以不管模型怎么说 当代理记录错误 脚本会带着原因发回来 在别人给邮件分级之前.

### 运行它

```bash
npm install @archmax-ai/harness langchain zod
```

`lookup_customer` 财务报告和审定财务报表 `send_email` 是你们的系统,作为普通的LangChain工具:

```js
// tools.js
import { tool } from "langchain";
import { z } from "zod";

const customers = {
  "ann@example.com": { name: "Ann", order: { id: "ORD-1001", status: "delivered" } },
  "bob@example.com": { name: "Bob", order: { id: "ORD-1002", status: "shipped" } },
};

export const lookupCustomer = tool(async ({ email }) => JSON.stringify(customers[email] ?? null), {
  name: "lookup_customer",
  description: "Look up a customer and their latest order by email address.",
  schema: z.object({ email: z.string() }),
});

export const sendEmail = tool(
  async ({ to, body }) => {
    console.log(`To ${to}:\n${body}`);
    return "sent";
  },
  {
    name: "send_email",
    description: "Send an email to the customer.",
    schema: z.object({ to: z.string(), body: z.string() }),
  },
);
```

```js
// index.js
import { createAgent } from "@archmax-ai/harness";
import { lookupCustomer, sendEmail } from "./tools.js";

const agent = await createAgent({
  workflow: "refund",
  tools: [lookupCustomer, sendEmail],
  workspace: { rootDir: import.meta.dirname },
});

const outcome = await agent.workflow.send("ticket-1001", {
  message: "Hi, I'd like a refund for my last order.",
  variables: { email: "ann@example.com" },
});

console.log(outcome.kind); // "completed"
console.log(outcome.auditTrail.map((step) => `${step.kind} → ${step.to}`).join("\n"));
```

```text
completed
trigger → decide
agent → check-decision
code → review-email
grader → send
```

一个电话是一转 `outcome` 说它是如何结束的: `completed`, (中文(简体) ), `parked` (等待一个人) 或事件),或 `failed` (代理人打电话 `archmax_raise` 因为工作无法完成). 这个 线索记录了每一个动作 是谁做的 届会具有持久性,在 `sessions/` 默认,所以 `send` 与同样的身份 继续谈话.

### 国家行动倡议

工作流程也从命令线上流出 只需要带子的工具 参考文献 工作空间 [`examples/customer-support/`](https://npmcn.com/package/%40archmax-ai/harness/examples/customer-support/) 是一个,它是套房 端到端测试以真实模式进行:

```bash
npx archmax run order-lookup "Which orders are delayed for Acme?" --root examples/customer-support
npx archmax test order-lookup --root examples/customer-support       # run the workflow's cases
npx archmax validate order-lookup --root examples/customer-support   # static checks, no model calls
```

退款的例子需要你的两个工具,所以它从你的代码中运行. 见 [CLI 参考](https://harness.archmax.ai/reference/cli/) 页:1 `sessions`, (中文(简体) ), `decide`, (中文(简体) ), `reply` 财务报告和审定财务报表 `deliver`。 。 。 .

### 下一个

-   [年级和代码状态](https://harness.archmax.ai/guides/automated-states/): 检查图表
-   [人类国家](https://harness.archmax.ai/guides/workflow-machine/#human-in-the-loop-states):一个人挑边
-   [触发器](https://harness.archmax.ai/guides/triggers/): 键入输入和返回,对其值、文件的规则
-   [测试](https://harness.archmax.ai/guides/testing/)情况: `archmax test`
-   [公共 API](https://harness.archmax.ai/reference/public-api/)数字 : `createAgent`、结果、活动

### 用编码代理撰写

写作技巧教一个编码代理 计划,年级和代码状态,治理,人 国家、案件和《国家国际法》。 装入 [技能水平](https://skills.sh/)数字 :

```bash
npx skills add archmax-ai/harness
```

从GitHub安装最新版本。 将技能定在您的项目 SDK 版本 取决于,在包中安装运出的副本,然后 `npm install`数字 :

```bash
npx skills add ./node_modules/@archmax-ai/harness
```

对于技能 中间软件 在你自己的经纪人 `BUNDLED_AUTHORING_SKILL_DIR` 导出决定 包装副本。 来源是 `skills/archmax-harness/`。 。 。 .

## 文档

-   [快速启动](https://harness.archmax.ai/getting-started/quickstart/) 财务报告和审定财务报表 [安装](https://harness.archmax.ai/getting-started/installation/)
-   指南: [工作流程机](https://harness.archmax.ai/guides/workflow-machine/), (中文(简体) ), [年级和代码状态](https://harness.archmax.ai/guides/automated-states/), (中文(简体) ), [会议](https://harness.archmax.ai/guides/sessions/), (中文(简体) ), [触发](https://harness.archmax.ai/guides/triggers/), (中文(简体) ), [技能](https://harness.archmax.ai/guides/skills/), (中文(简体) ), [子工作流程](https://harness.archmax.ai/guides/sub-workflows/), (中文(简体) ), [测试](https://harness.archmax.ai/guides/testing/), (中文(简体) ), [符号效率](https://harness.archmax.ai/guides/token-efficiency/)
-   参考: [机器光谱](https://harness.archmax.ai/reference/machine-spec/), (中文(简体) ), [国 际](https://harness.archmax.ai/reference/cli/), (中文(简体) ), [公开 API](https://harness.archmax.ai/reference/public-api/), (中文(简体) ), [词汇表](https://harness.archmax.ai/reference/glossary/), (中文(简体) ), [更改日志](https://harness.archmax.ai/reference/changelog/)

## 发展

```bash
npm run dev -- run order-lookup "..." --root examples/customer-support
npm run typecheck && npm test
npm run docs:dev
```

实质性变化通过 [打开Spec](https://github.com/Fission-AI/OpenSpec) 下级 `openspec/`文献, `README.md` 和写作技巧的飞船在与 他们描述的行为。 见 [捐款额](https://npmcn.com/package/%40archmax-ai/harness/CONTRIBUTING.md) 编辑 [开发设置](https://harness.archmax.ai/contributing/development/)。 。 。 .

## 许可证

麻省理工学院. 见 [自由主义](https://npmcn.com/package/%40archmax-ai/harness/LICENSE)。 。 。 .

## 常见问题

### @archmax-ai/harness 是什么？

特工们无法可靠地遵循程序 亚克马克斯的拉带让他们: 在LangChain Deep Agents之上的规范层 在每个步骤上执行一个宣告性的工作流程状态机器\.

### 如何安装 @archmax-ai/harness？

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

### @archmax-ai/harness 支持 TypeScript 吗？

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

### @archmax-ai/harness 支持 ESM 还是 CommonJS？

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

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

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

### @archmax-ai/harness 可以商用吗？

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

### @archmax-ai/harness 的下载量有多少？

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

### @archmax-ai/harness 还在维护吗？

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