# @agentium/harness 中文文档

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

版本：4\.11\.0
npm 元数据更新时间：2026-10-23T22:19:42.428Z
中文译文更新时间：2026-11-08T08:02:33.040Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.1 MB，128 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^22\.18\.0 \|\| ^24\.11\.0
- 运行依赖：1 个
- peer 依赖：@agentium/core ^4\.11\.0
- 首次发布：2026-10-04T14:14:13.992Z
- 最新版本发布：2026-10-23T22:19:42.259Z
- 近 30 天下载量：1859（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

Agentium 工具、上下文、中件和预设的可编译的带子开发工具包

## 安装

```sh
npm install @agentium/harness
```

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

## README

# @ agentium/ 痛苦

从明确的能力、政策和驱动力建立代理执行环境的开发者工具包. `HarnessRuntime` 拥有组成,范围资源,犬话谈话状态,总预算,事件和清理. 核心 `Agent` 拥有普通模型/工具执行并消耗中性 `ExecutionServices` 端口;它不构造一个吊带或依赖于此套件.

定义可以贡献出工具,源上下文,即时碎片和订购的中间软件. 定义、扩展和检查是同步的,没有进行文件系统扫描、提供者呼叫或客户端初始化。 装订和执行从运行时间开始.

这个 [可靠性指南](https://npmcn.com/package/%40agentium/harness/DEPENDABILITY.md) 显示三种完整的路径:普通代理、在使用赠款/预算下相同的配置,以及经核实的完成和评价的可选证据连续性。 它还确定了资源所有权、来源信任、不完全结果、储存迁移和回收限度.

这个 [执行图表指南](https://npmcn.com/package/%40agentium/harness/EXECUTION-GRAPHS.md) 包括有栅栏的图恢复、共享根输入、经核准的工具DAG规划以及仅待流修订.

## 建设和使用

安装匹配版本 `@agentium/core` 财务报告和审定财务报表 `@agentium/harness`,加上你选择的供应商SDK。 此软件包没有需要的浏览器,队列或提供者SDK依赖性. 无害环境管理和共同JS出口暴露出相同的API。 在这个工作区:

```sh
npm run build:core
npm run build:harness
```

使用驱动程序和明确的主机赠款定义:

```ts
import { agentDriver, HarnessRuntime, research } from "@agentium/harness";

// model is the application's existing ModelProvider.
const definition = research({
  text: {
    id: "project-notes",
    entries: [{ id: "scope", text: "The project investigates shipping delays.", uri: "notes:project" }],
  },
});
const runtime = new HarnessRuntime({
  definition,
  driver: agentDriver({
    name: "research-assistant", model,
    instructions: "Answer questions using the supplied sources and cite them.",
  }),
  grants: { toolIds: [], modelRoles: ["main"] },
  budgets: { maxModelCalls: 4, maxToolCalls: 0, maxTokens: 8000 },
});
const result = await runtime.run("What is this project investigating?", {
  identity: { tenantId: verifiedTenant, userId: verifiedActor },
  sessionId: "research-42",
});
```

`research` 不进行隐含的网络搜索。 文本和文件被标记为源数据. 搜索和商务工具来自主机,在模型使用之前必须授予它们的名字. 身份来源于信任的应用程序认证,从不模式输入.

## 代理所有权和配置

`agentDriver(config)` 创建一个运行中的代理,在核心之外应用定义默认,并在该运行中在整个后续和完成修改中重复使用该实例。 不同的运行得到不同的代理。 运行时间关闭自有代理在自有工作后结算一次;清理故障为诊断性故障,不取而代之为主故障. 提供主机的后援商店仍被借入,不由该司机关闭.

`agentDriver(existingAgent)` 借用已经配置的代理 。 宿主所闭. 对被借用的 Agent 有代理默认或限制的定义被拒绝:选择一个配置所有者. 如果借款人的定义没有违约或限制,则借款人仍可获得债务、定期赠款、预算和政策.

明确的代理配置超越定义默认值,包括 `false` 以禁用一个特性。 定义限制上限配置代理工具回合和子深度; 运行时间 `budgets` 各代表之间独立捆绑的汇总模型/工具/托盘使用和修订. `projectRoot` 被运行时间所抓住并解决相对的工作空间和技能路径。 可移动的显示路径仍然相对散列.

Canonical的谈话属于运行时间的会话商店. Agent适配器通过中性执行服务端口提供历史,并使用ephemeral Agent会话语义,避免重复会话持久性或自动内存提取. 明确的内存工具和常备笔记是独立的能力. 运行中的租户/用户身份不会自动给任意主机存储客户端取名:提供租户/演员范围商店和客户端,并与主机保持关闭状态.

## 从Agent.deep的明显迁移

`Agent.deep()`, (中文(简体) ), `AgentConfig.harness`, (中文(简体) ), `harnessOptions`,探员 `replaceTools`,则 `legacyDeep` 预设被删除。 没有隐藏替换预设 。 旧的选择可以写成一个普通的定义,然后单独调整或删除:

```ts
import { InMemoryStorage } from "@agentium/core";
import { agentDriver, defineHarness, HarnessRuntime } from "@agentium/harness";

// One approved tenant/actor's backing storage. InMemoryStorage is not durable.
// For persistence, supply your host-owned storage scoped to that tenant/actor.
const tenantStorage = new InMemoryStorage();
const definition = defineHarness({
  id: "project-agent",
  defaults: {
    workspace: { path: ".", mode: "write" }, // Explicit host-disk write access.
    skillDirs: ["skills"],
    contextFiles: true,
    filesystem: true,                       // Virtual files, not the host disk.
    subagents: true,
    fileMemory: true,
    searchPastSessions: true,
  },
  limits: { toolRoundtrips: 10, maxChildDepth: 2 },
});
const runtime = new HarnessRuntime({
  definition,
  projectRoot: "/srv/approved-project",
  driver: agentDriver({
    name: "project-agent", model,
    // Standing notes and virtual files reuse this explicit backing store.
    // Automatic Agent session storage/extraction is disabled during controlled runs.
    memory: { storage: tenantStorage, summaries: false },
  }),
  grants: {
    toolIds: [
      "fs_read_file", "fs_list_directory", "fs_file_info", "fs_write_file",
      "list_skills", "get_skill_instructions", "get_skill_reference",
      "agent_fs_write", "agent_fs_read", "agent_fs_list", "agent_fs_search",
      "memory", "task", "search_past_sessions",
    ],
    modelRoles: ["main"],
  },
  budgets: { maxModelCalls: 12, maxToolCalls: 20, maxTokens: 16000 },
  executionPolicy: hostPolicy,
});
await runtime.run("Inspect the project", {
  identity: { tenantId: verifiedTenant, userId: verifiedActor },
  sessionId: "project-session",
});
// Close tenantStorage only when its host scope has finished using it.
```

给 `model`, (中文(简体) ), `hostPolicy` 并且核实的身份是应用程序的依赖性。 定义复制了前一个特性选项, 而非隐含权限: 删除 `fs_write_file` 赠款或使用 `mode: "read"` 当写作是不必要的。 Core 拒绝字符串工作空间 。 主机-文件封禁检查静态路径出逃;对敌对并发的文件系统突变使用OS隔离.

没有明确共享存储,配置的 Agent 虚拟文件系统和文件内存每跑都新鲜. 由于上述范围存储,常备笔记和虚拟文件在随后运行的Agent实例中幸存. `search_past_sessions` 搜索 Agent 配置的后置存储器中的会话; 它不搜索 habel 会话存储 。 哈尼斯犬科历史保持独立. 默认吊带存储和 `InMemoryStorage` 过程是局部的和不可延长的.

儿童得到相同的控制下处决界限、政策、身份和取消,并有新鲜儿童谈话/状态。 他们没有重新定义或隐含地获得所有母代理默认。 授权仍受分摊总预算的约束. [深层移民. test.ts](https://npmcn.com/package/%40agentium/harness/src/__tests__/deep-migration.test.ts) 使用真正的代理执行和假的提供者来行使明确的选择权,包括根深蒂固的技能/项目背景、书面拒绝、授权预算、持续说明和成功/失败清理.

## 定义自定义能力

```ts
import { agentDriver, defineAbility, defineHarness, HarnessRuntime } from "@agentium/harness";

interface NotesService { read(query: string, userId?: string): Promise<string> }
const notes = defineAbility({
  type: "example/notes",
  validate: (options: { service: NotesService }) => ({ service: options.service }),
  describe: () => ({ toolNames: [], requirements: ["notes:read"], runtimeDependent: true }),
  bind: async ({ service }) => ({
    tools: [],
    contextSources: [{
      id: "notes",
      fetch: async (query, run, budget) => {
        run.signal?.throwIfAborted();
        const text = await service.read(query, run.userId);
        return [{ id: "result", text, trust: "source", byteLength: Buffer.byteLength(text) }];
      },
    }],
    middleware: [{
      id: "notes-observer",
      afterModel: async (_response, run) => { run.signal?.throwIfAborted(); },
    }],
    // Dispose resources created by this binding only; service is host-owned.
  }),
});
const runtime = new HarnessRuntime({
  definition: defineHarness({ id: "support", abilities: [notes({ service: notesService })] }),
  driver: agentDriver({ name: "support", model }),
  requirements: ["notes:read"],
  grants: { toolIds: [], modelRoles: ["main"] },
});
```

选项仍按静态输入,包括回调和服务. `validate` 必须是纯洁的。 平面物体/阵列被描绘成不可改变的配置;提供新的容器来装订/描述。 函数和类例仍然是调用人拥有的参考文献。 代表对身份敏感的 SDK 客户端作为类例. 信任的工厂不是沙箱.

装订每次运行时按顺序初始化一次并按倒序处理一次,包括部分初始化失败. 重用一个定义会产生单独的运行约束;运行中的儿童执行共享所提供的服务. 不关闭在 `dispose`。 。 。 .

源获取器接收条目/字节/token/死线边框和取消信号;运行时检索应用了源的中央限制. 源估计不是权威,检索数据不能成为主机指令. 中间软件ID必须独一无二; 稳定 `before`编号 :`after` 命令拒绝未知的引用和循环。 模型转换保存了主机指令和提供/工具续作组. 观察员得到孤立的、结构化的、可实现的反应/结果。 Middleware不能取代强制工具执行.

## 编写、检查和替换

```ts
import { defineHarness, extendHarness, describeHarness, textContext } from "@agentium/harness";

const original = defineHarness({
  id: "product",
  abilities: [textContext({ id: "notes", entries: [] }, { instanceId: "notes" })],
});
const extended = extendHarness(original, {
  id: "product-specialized", disable: ["notes"],
  abilities: [customAbility({ service })],
});
console.log(describeHarness(extended));
```

检查报告申报和诊断没有约束力,发现证书或串行可执行选项。 使用明确的能力实例ID来重新使用定义.

-   默认的继承; `false` 禁用 。 技能-指令缺省; `false` 清除他们.
-   `disable` 删除整个能力的工具,上下文和中间软件. `replaceAbilities` 明确替换已有实例ID.
-   复制工具/文本/中件/即时ID失败 。 执行前替换能力或主机工具集; Agent 没有成分替换选项 .
-   所需经费是明确的运行时间东道方赠款,而不是依赖性安装。 运行时间赠款/政策/身份不能通过定义或模式产出加以扩大.

## 文本和文件上下文

`textContext({ id, entries }, { instanceId })` 即刻取出UTF-8源条目,并拥有被批准的便携式工厂. `fileContext({ id, root, files }, { instanceId })` 仅读取一个明确的绝对根下的固定主机选择路径。 获取时会读取; canonical path, UTF-8 和大小检查应用. 它不提供全工作空间的工具.

```ts
const runtime = new HarnessRuntime({
  definition: research({ files: { id: "project-files", root: "/srv/project", files: ["README.md"] } }),
  driver: agentDriver({ name: "research", model }),
  projectRoot: "/srv/project",
  requirements: ["filesystem:read"],
  grants: { toolIds: [], modelRoles: ["main"] },
});
```

`research` 禁用自动工作空间工具,上下文文件发现,文件内存和子代理. `suppliedTools({ tools, requirements? })` 在不执行或冻结的情况下包裹信任的工具Defs. `base({ id?, abilities?, defaults? })` 提供一个组成壳.

## 便携式清单

```ts
import { defineHarness, exportManifest, hashManifest, loadManifest, textContext } from "@agentium/harness";

const definition = defineHarness({
  id: "portable-notes",
  abilities: [textContext({ id: "notes", entries: [{ id: "one", text: "Source text" }] }, { instanceId: "notes" })],
});
const manifest = exportManifest(definition);
const hash = hashManifest(manifest);
const loaded = loadManifest(JSON.parse(JSON.stringify(manifest)), [textContext.factory!]);
```

装入需要经过批准的工厂登记;JSON从不包含可执行工厂. 未知的密钥,不兼容的版本,缺失的工厂和非JSON选项失败. 出口需要明确的驾驭/便携式能力识别和绘图。 本地回调,客户端,文件能力和工具都留在本地,除非其作者提供经批准的等效映射. 证书从不属于清单.

自定义 `defineAbility` 绘图使用情况 `portable: { validateOptions, toOptions, toJSON }` 并揭露 `factory`. Hashes 覆盖经验证的 Canonic 显示的 JSON , 而非函数文本, 活客户端或解析的绝对路径 。 导出代理配置和带子分别显示; 核心代理序列化中没有带子运行时间定义 .

## 核查和限制

```sh
npm run build:core
npm run build:harness
npx vitest run packages/harness/src
AGENTIUM_TEST_PACKAGES=1 npx vitest run packages/harness/src/__tests__/package-consumption.test.ts
```

选入包测试将本地的柏油球安装到一个孤立的离线消费者身上,并验证ESM/CJS和公共TypeScript的用法,没有可选的提供者/浏览器/排队SDK. 首先构建如此陈旧的输出, 无法进行源码验证 .

本地运行时间不提供持久恢复,分布式所有权,远程政策截取,技能沙箱,浏览器/媒体传输或视觉编辑器. 这些要求有明确的合并或回收合同。 主机能力是信任的代码,而不是JavaScript安全边界.

## 执行司机和运行把手(H2)

`HarnessRuntime` 拥有范围限定的会话租赁、总召集预算、强制性 执行政策、事件历史、完成检查和清理。 驱动控件 进展情况 `start(request, services)`. 提供服务的模式 通过所使用的同一批准和执行边界的呼叫和发送效果 以 `Agent`. 驱动程序执行和主机装订是可信赖的应用程序代码; 此接口不包含沙盒 JavaScript 或截取任意的网络呼叫 .

```ts
import { Agent, defineTool } from "@agentium/core";
import { HarnessRuntime, agentDriver } from "@agentium/harness";
import { z } from "zod";

// model is the application's existing ModelProvider.
const lookup = defineTool({
  name: "lookup", description: "Read an approved record",
  parameters: z.object({ id: z.string() }),
  execute: async ({ id }) => records.read(id), // host-owned record service
});
const agent = new Agent({ name: "assistant", model, tools: [lookup] });
const runtime = new HarnessRuntime({
  driver: agentDriver(agent, { stream: true }),
  grants: { toolIds: ["lookup"], modelRoles: ["main"] },
  budgets: { maxModelCalls: 8, maxToolCalls: 6, maxTokens: 8000 },
  executionPolicy: {
    decide: () => ({ action: "allow" }),
    resolveEffect: () => "read",
  },
});
const handle = runtime.start("Read record 42", {
  identity: { tenantId: verifiedTenant, userId: verifiedActor },
  sessionId: "conversation-42",
});
for await (const event of handle.events()) render(event);
const result = await handle.result();
// runtime.run(input, options) returns that same terminal result.
```

A 类 `RunHandle` 报告一个最终结果: `completed`, (中文(简体) ), `failed`, (中文(简体) ), `cancelled`, (中文(简体) ), `stopped`,或 `awaiting_input`。终端事件包含同样的 结果和最后光标. `cancel()` 记录意图并传播信号; 和解和资源释放等自有工作开始。 提供者或 忽略取消的自定义驱动程序可以延迟和解。 开始于外部 效果永远不会回滚。 关闭一个活动 显示器只关闭该查看器. 同时代的传记员被命令阅读. 默认事件历史保留 256 事件; 与 `events({ after: cursor })`。接收的旧光标 `HarnessEventGapError`大型终端产出成为标出范围的文物参考; 找回来 `runtime.getArtifact(identity, sessionId, artifactId)`。 。 。 .

内置驱动程序支持已队列 `follow_up` 输入。 内置代理驱动器也 支持 `steer` 在完整的工具回合边界。 自定义驱动程序可以声明 `steer` 用它来消耗 `services.takeInput()`。用于现场提问 `requestInputTool()` 或者说 `await services.requestInput()`,然后回答 `handle.reply(requestId, input)`。 。 。 . `handle.state === "awaiting_input"` 非绝对性质; `result()` 预算得到保留。 返回旧终点站 `awaiting_input` 状态是遗留下来的,而不是活的中止.

见 [对话运行](https://npmcn.com/package/%40agentium/harness/CONVERSATIONAL-RUNS.md) 为时钟,输入事件, 公共信息、提供者能力、流畅相容性和紧凑性. 不支持的控件抛出 `HarnessUnsupportedError`中断和替换, 远程政策覆盖面和持久复苏仍然得不到支持。 记忆 活动、文物、会议和待决问题显然不可持久.

东道方赠款是上限。 主计长只选择核准的工具/模式角色; 删除所需的工具或选择未支持的模型选项失败 . 示范产出限额被限制在剩余的象征性津贴和保留地 防止同时发出的呼吁分担该津贴。 报告的使用情况包括: 输入和提供者推理符号,所以提供者的实际核算可能超过 输出估计值; 运行时区块在耗尽时会随后调用。 型号 调用/工具尝试限制是独立执行的。 背景策略返回一个 不可改变的请求投影和出处;犬科历史保持不变. 不透明提供者的延续不能在模式角色之间迁移.

```ts
const completionPolicy = {
  id: "require-evidence",
  evaluate: async ({ text, revision }) => text.includes("Evidence:")
    ? { action: "accept", reason: "Evidence included" }
    : { action: "revise", reason: "Missing evidence", instruction: "Include Evidence: and its source." },
};
// Supply completionPolicy and budgets: { maxRevisions: 1 } to HarnessRuntime.
// Revisions cannot execute tool effects unless allowRevisionEffects is explicitly true.
```

## 工作流程、团队和定制司机

`workflowDriver(workflow)` 接受 JSON 对象输入补丁并保存 工作流构造器的另一个初始状态. 每个函数步骤都作为 `workflow:<stepName>` 政策、核准和预算 检查。 确定性核准工作流程只能提供 `workflow:submit`设置 `executionPolicy.decide` 改为 `ask`,并输入主机 `ApprovalManager`。 。 尚待处理的请求包括经核实的租户和行动者。 已拒绝的步骤返回 a 终端结果失败, 不执行回调 。 受控函数 步骤不会自动重试效果.

`teamDriver(team)` 使用现有的团队算法。 代理人收到 同一身份、取消、政策和总模式/工具预算。 远程团队 成员显然失败了,因为这一运行时间无法拦截其影响. 根历史和每个授权代理的完整工具/提供者对话 在会话快照中单独保留 `history` 财务报告和审定财务报表 `conversations`。 。 。 . 失败/流产的部分笔录保留在 `replayable: false`。 。 。 .

```ts
import type { ExecutionDriver } from "@agentium/harness";
import { testDriverContract } from "@agentium/harness/testing";

const deterministic: ExecutionDriver = {
  id: "example/deterministic", version: 1,
  capabilities: { controls: [], durable: false, policyCoverage: "local", controlledExecution: true },
  async start(request, services) {
    services.append([{ role: "user", content: request.input }]);
    const result = await services.dispatch({ id: "read-1", name: "lookup", arguments: { id: "42" } });
    const text = result.error ?? String(result.result);
    services.append([{ role: "assistant", content: text }]);
    return { text };
  },
};
await testDriverContract(deterministic, {
  tools: [lookup], grants: { toolIds: ["lookup"], modelRoles: [] },
});
```

明确的测试子路径没有维特依赖性,并检查终端/结果 协议、命令身份、最后光标和定居结果的不可更改性。 这个 执行呼叫器提供的固定设备;应用程序必须额外测试自己的设备 驱动程序的效果、取消合作以及控制边界.

## 会话所有权和便携式运行时间参考

默认商店拒绝向同一个租户/演员/会议提供第二个写作员 `HarnessSessionConflict`其宣布的担保是程序-当地单写 安全,没有比对和擦擦, 没有耐久性。 不同的租户仍然孤立. 通过 `services.resource(id, "session", initialize)` 被重用直到 `runtime.resources.closeSession(identity, sessionId)` 毕竟 租赁释放。 运行一次逆向收购时关闭的资源;主机拥有 客户从不处理。 清理诊断不能取代主要结果. 应用程序拥有保留会话/艺术库和明确会话清理.

配置运行时间的定义 。 核心特工没有带状成分 选项。 运行时间绑定应用工具,提示, 上下文源,以及用于自定义驱动模型/效果服务的中间软件. 代理适配器使用 `history` 加号 `ephemeral: true` 语义学, 离开峡谷 持续保存并避免重复代理会话记录. 在绳子外, `agent.run` 财务报告和审定财务报表 `agent.stream` 接受 `ephemeral: true` 用于 外部拥有的历史没有自动会话/记忆的持久性.

当地 `defineHarness({ runtime: { driver, controller, contextPolicy, completionPolicy } })` 接受信任的直接执行。 便携式清单 仅包含 `runtime` 登记处参考资料 `{ id, version }`,加上角色对主机 约束性偏好。 对导出, 提供匹配 `runtimeReferences` 财务报告和审定财务报表 `runtimeRegistry` 测绘. `loadManifest(manifest, abilityFactories, runtimeRegistry)` 仅解决明确核准的执行问题,但未能完成 缺少或模糊的参考文献。 没有导出映射的可执行引用 失败的精确 `runtime.<field>` 路径。 全权证书和客户仍留在当地.

`Agent`是因为 `checkpointing` 选项现在记录工具回合记录/状态 抓图并曝光配置 `checkpointManager`。这些快照支持 检查; 删除后期快照不会取消效果或恢复运行 。 持久性 第004号计划要求单独签订回收/操作领导合同.

控制下执行拒绝普通Agent反射,模型后置压缩/工具-结果汇总, 工作开始前以例外方式交接 使用 `completionPolicy`, (中文(简体) ), `contextPolicy`团队/司机代表团,因此,每个模式 调试和修订仍须遵守运行时间的预算和效果政策. 纯上下文修饰仍然可用。 保留普通代理配置 他们现在的行为 授权 `RunOpts.executionPolicy` 是额外的 强制性限制,不能放松代理政策或运行时间补助.

### 预算思考和摘要

使用 `reflectionPolicy` 财务报告和审定财务报表 `summaryContextPolicy` 模型支持的完成和 h2 中的上下文处理 它们的辅助模型是明确的主机绑定:

```ts
import { reflectionPolicy, summaryContextPolicy } from "@agentium/harness";

const runtime = new HarnessRuntime({
  driver: agentDriver(agent),
  grants: { toolIds: [], modelRoles: ["main", "critic", "summary"] },
  models: {
    critic: { provider: criticModel, options: ["maxTokens"] },
    summary: { provider: summaryModel, options: ["maxTokens"] },
  },
  budgets: { maxModelCalls: 12, maxTokens: 16000, maxRevisions: 1 },
  completionPolicy: reflectionPolicy({
    modelRole: "critic", criteria: "Support factual claims with supplied evidence.",
    maxTokens: 512,
  }),
  contextPolicy: summaryContextPolicy({
    modelRole: "summary", maxContextTokens: 6000, keepRecentTurns: 2,
    summaryMaxTokens: 1000,
  }),
});
```

批评者必须返回一个严格的JSON完成决定. 错误的决定, 截断的响应和出乎意料的工具请求都未能关闭 。 订正份额 运行时间的总预算,并且不能引入效果,除非主机 启用 `allowRevisionEffects`政策本身从未执行工具.

摘要只替换模型请求中较旧的完整转折. 东道主 指示和最近选定的整个转弯保持完整,包括不透明 提供者的延续和工具/成果组。 摘要被标注为不信任 历史数据;舟山历史未变. 帮助者拒绝 近代不可分割的转折、超大源或超大摘要而不是默默 截取取来. `maxInputBytes` 默认为65536. 吻合是一种估计; 供应商背景核算可能有所不同。 已绑定的请求不作摘要 电话 新的超大投影可能会引起另一次有限度的即时呼叫.

自定义驱动程序可以使用 `services.controlModel(role, messages, options)`具体利用政策可以缩小其中立性 `ctx.executionServices` 改为 `HarnessExecutionServices` 以访问扩展. 这需要明确授予和约束的角色,并有允许的选项密钥. 呼叫共享模式/账户预算、取消、事件核算和自有工作 和解。 它们没有工具或提供者的延续,也不改变 任务中的积极作用/工具。 它们跳过任务控制器,上下文预测和能力 防止政策再起的中间软件;其权威来自明确 主办角色奖. 遗留物代理反射/压缩配置仍被看守 明确选择这些政策端口.

自定义驱动程序可以通过此程序登记额外的同步授权工作 `services.runOwned(operation)`; 运行时间等待工作后释放 会期租赁和资源。 内建代理工具执行使用此所有权 路径。 团队广播和协作等待每个开始的成员,包括装订清理,在失败时解决. 合规帮助者还处理其固定会话中创造的资源, 包括验证失败时,同时保留主失败.

### 持久表

`DurableWatch`, (中文(简体) ), `defineWatch`,以及 `gmailWatchSource` 明确启用, 授权监督核心持久任务/行动合同。 东道方用品 恒定存储器,调度器,认证的Gmail客户端和触发验证器, 和一个范围化的通知连接器。 盲从 光标/潜水 安静 小时数、发送上限和模棱两可的效果调节都包括在内。 见 [监视指南](https://npmcn.com/package/%40agentium/harness/src/watch/README.md) 设置、事故恢复保障和 其余为Gmail/Pub/Sub送货门.

### 核准的多边协商进程资源

`mcpResources` 通过主机认证的 MCP 客户端添加文本文档作为受约束上下文. 它在结构上接受客户,包括MCP SDK世代; Agentium 不自动安装资源 SDK .

```ts
import { defineHarness, mcpResources } from '@agentium/harness';

const definition = defineHarness({ abilities: [mcpResources({
  id: 'approved-documents',
  resources: [{ uri: 'docs://policies/shipping', mimeTypes: ['text/markdown'] }],
  authorize: (grant, ctx) => host.canRead(ctx.tenantId, ctx.userId, grant.uri),
  connect: async (ctx) => {
    const client = await host.connectMCP(ctx); // authenticates this principal; respects ctx.signal
    return { client, dispose: () => client.close() };
  },
})] });
```

`host` 代表应用程序自主认证,授权和连接代码. Grant URIs和MIME类型是准确的. 可选主机 `select(query, ctx)` 能够选择这些赠款的子集;没有全服务器的发现可以扩展访问。 设置默认为五秒期限( E)`connectTimeoutMs`),并处理延迟连接。 资源读取符合共享上下文条目/字节/死线预算并运行取消 。 在读取和返回内容之前重新检查授权 。 SDK资源缓存被绕过;v1客户端忽略了该额外选项,不执行v2响应缓存. 检查每个返回的URI/MIME 。 文本被标记为源数据,带有出处,从未作为系统指令被插入. 二进制文档需要明确的主机解码器. 仅包含从核定格式/ URI 中解码的文本; 此能力本身不会执行或获取资源 URIs .

### 自定义驱动程序和控制器遥测

```ts
import { EventBus } from '@agentium/core';
import { HarnessRuntime } from '@agentium/harness';
import { instrumentBus } from '@agentium/observability';

const telemetry = new EventBus();
const observation = instrumentBus(telemetry, { exporters: ['console'] });
const runtime = new HarnessRuntime({ ...runtimeConfig, telemetry });
await runtime.run('task', { identity, sessionId });
await observation.shutdown();
```

运行时间输出一个运行周期, 唯一识别的模型引用 `services.model`, (中文(简体) ), `streamModel` 财务报告和审定财务报表 `controlModel`,并且控制器跨度为 `prepareRun`, (中文(简体) ), `prepareStep` 和完成评价。 决定包括动作,所选择的模范角色和活性工具计数. 成功、失败和取消都结束了 观察失败不能控制执行. 在这些事件中省略了提示、输出文本、控制器解释和工具参数.

使用这辆公交车与自己的采集器在观察吊带时使用. 不将相同的追踪器或度量衡采集器附加到带子总线和包裹的Agent总线上:这些层共享执行ID并描述重叠的工作. 绕行执行服务的直接提供者呼叫也绕过运行时间预算和遥测;自定义驱动器应当使用服务. 现有公共汽车上仍然有运输/工具包专用追踪工具.

### 资源预算和完成工作

`HarnessRuntime` 在提交每个模型之前保留预测投入和产出 电话 输入包括预测的信息、工具图和不透明提供者 继续。 一个同步 `estimateInputTokens({ provider, messages, tools })` 选项可以提供特定供应商的保守约束; 默认估计器 是一种建议。 产出上限为预测投入后的现有余额. 同时任务,控制,和完成操作 共享允许。 调用空档 在控制器/文本投影之前保留,并在准备时发布 失败而不消耗一个逻辑的呼叫.

```ts
const runtime = new HarnessRuntime({
  driver,
  grants: { toolIds: [], modelRoles: ["main", "finisher"] },
  models: { finisher: { provider: model, options: ["maxTokens"] } },
  budgets: {
    maxModelCalls: 12,
    maxTokens: 80_000,
    finishingModelCalls: 1,
    finishingTokens: 6_000,
  },
  completionPolicy,
});
const handle = runtime.start("task", { identity, sessionId });
console.log(handle.budget.tokens); // limit, used, reserved, remaining,
                                  // finishingReserved, ordinaryRemaining
```

快照可从 `handle.budget`, (中文(简体) ), `services.budget`,以及 `result.budget`. 伯爵使用逻辑模型调用, 策略允许的工具尝试, 和总输入 + 输出符号. `null` 限制/保留指无限. `remaining = max(0, limit - used - reserved)`· ; `finishingReserved` 是受保护的 未承付的余额在该总数之内 `ordinaryRemaining` 把它排除在外. 已知惯例取代了预定的象征性保留,包括逾期使用 取消 。 保留总是被解除。 已经开始但无 全部使用量以保守和递增方式消耗其预测 `unknownUsageCalls`报告 `result.usage` 实际收到的证据; 它可能不同于保守的充电 `result.budget.tokens.used`。 。 。 .

信任的驱动程序或完成控制器可以调用 `services.finishModel("finisher", messages, { maxTokens: 2_000 })`明确 使用完成能力(加上现有的普通能力),需要给予, 明确约束角色,只接受完整的无工具响应. 正在返回 驾驶员的考生还在申请 `completionPolicy`; 补全 不绕过证据验证或授权工具/效果。 普通工作和 重复拒绝预算不能消耗期末储备金。 无额外津贴 在配置的总数上添加.

这些是按业务预测的资源预算,与核心的存储支持分开 货币预定。 记录实际供应商超支情况并减少未来 承认; 估计数不能保证硬体的上限。 未知的 SDK 这里看不到重试消耗 。 对于严格的宿主,供应保守 输入估计、 限制输出、 禁用内部重试、 并选择明确 主机重试/会计政策。 无最大值的无限符号预算 无法保守约束未知输出使用.

### 居民历史和东道国档案

请求上下文投影仍保留着条子记录 选择到 `residentHistory: { maxMessages, maxBytes?, archive, canEvict? }` 移动旧的关闭 从驻地记忆变成主机拥有的档案. `archive.write(scope, reference, messages)` 在解决之前必须确认存储; `archive.read(scope, reference)` 返回原始记录。 无存储后端 被捆绑。 参考文献包括对话的ID、计数和SHA-256摘要和 持续为: `HarnessSessionSnapshot.archivedHistory`。 。 。 .

限制在模式/会话边界上适用。 整个用户回合是 原子,包括每一个并行的工具调用/结果和不透明回放项目. 东道主 指令和最近的转折停留在居民中;超大小的不可分割转折 失败 `HistoryRetentionError`. 存档失败使本地记录完好无损. 失败快照即使不符合要求的限度,仍保留证据. 支持封闭的OpenAI回放/Anthropic回放组. 未知的不透明 有效载荷需要明确 `canEvict` 主机证明或提供者 `capabilities.historyEviction: "closed_turns"`; 明示 `"unsupported"` 拒绝 驱逐。 永远不要宣布支持需要被逐出房屋的供应商.

`services.history` 是本地重放窗口; `services.archivedHistory` 列表 存档引用 。 使用 `services.retrieveHistory(id)` 内 活动运行或 `runtime.retrieveHistory(identity, sessionId, id)` 运行之间. 检索核实计数/ digest 和工具结构;不自动插入 检索到信任的模型上下文中的记录 。 主机可以显示已检索 通过上下文政策将数据记录为源数据。 内置代理循环发布 被拆迁的初始/文本副本。 自定义司机拥有其额外副本,以及 平行的活跃儿童对话有独立的居住限制。 已完成 儿童笔录在成功开庭时全部存档。 存档参考 许多届会的元数据、主机存储保留和汇总限制仍然存在 东道方责任。 没有这种选择,现有的完整历史行为依然存在.

### 公共输入预验证

导入 `parseRunInput`, (中文(简体) ), `validateRunInput`, (中文(简体) ), `RUN_INPUT_LIMITS`,以及 `HarnessInputError` 从 `@agentium/harness`。 。 。 . `parseRunInput(encodedJSON)` 边框 在解析和验证 JSON 编码前的 UTF-8 字节 **信件内容值**, (中文(简体) ), 不是一个完整的回复信封. `validateRunInput(unknownValue)` 返回已验证的 复制时精确使用 `start`, (中文(简体) ), `send`,以及 `reply`。 。 。 .

冻结的限制暴露了 `maxEncodedBytes`编号 :`maxNormalizedBytes` (65 536个), `maxQuestionBytes` (32 768美元)和 `maxChoices` (100) (英语). 字节包括 JSON 引文和 逃出; 编码后的限制也算作空白 。 验证允许为空 字符串,但需要由严格形状的内容部分组成的非空阵列。 媒体 对有效载荷进行外形检查;针对供应商的媒体支持仍然是稍后的检查. 驳回请求不要求等待处理。 运行状态,请求关联, 已解答的回复、取消和超时将在 `reply(requestId, value)` 消耗它.

会话快照持续对话/状态;不会恢复活运行. 持久恢复需要改编的执行检查站、待投入状态和 效果的安全延续。 这项工作被推迟,如网页技术参考 检索:当前的内置技能工具仍然读取整个文件. 未来的呼唤 合同应包括稳定的抵消/修改和真实的遗漏标记.

## 执行图

使用核心 `Workflow` 图表/重复现有步骤 `workflowDriver`。不需要图数据库、额外的驱动程序或第二个代理环路。 完整 [工作流程指南](https://npmcn.com/package/%40agentium/core/src/workflow/README.md#dependency-graphs-and-bounded-replanning) 定义数据/控制边缘、连接、范围化身份、修复界限和检查站限制.

```ts
import { Workflow } from "@agentium/core";
import { HarnessRuntime, workflowDriver } from "@agentium/harness";

const workflow = new Workflow({
  name: "graph-example", register: false,
  initialState: { left: 0, right: 0, total: 0 },
  steps: [{
    name: "calculate", maxConcurrency: 2,
    graph: [
      { id: "left", step: { name: "read", run: async () => ({ left: 2 }) } },
      { id: "right", step: { name: "read", run: async () => ({ right: 3 }) } },
      { id: "sum", inputsFrom: ["left", "right"],
        step: { name: "sum", run: async (state) => ({ total: state.left + state.right }) } },
    ],
  }],
});
const runtime = new HarnessRuntime({
  driver: workflowDriver(workflow),
  grants: {
    toolIds: ["workflow:calculate/left/read", "workflow:calculate/right/read", "workflow:calculate/sum/sum"],
    modelRoles: [],
  },
  budgets: { maxToolCalls: 3, maxModelCalls: 0 },
});
const result = await runtime.run("{}", {
  identity: { tenantId: "verified-tenant", userId: "verified-user" }, sessionId: "calculation-1",
});
// result.structured.total = 5; trusted functions use the existing controlled effect port.
```

图表节点功能和代理工具保留东道方的赠款、核准政策、取消和总预算。 巢道节点工作可以超过外道节点同位素,而主机拥有外道资源锁定/同位素. WorkflowDriver返回最终状态和集合原因;直接Workflow结果包含节点诊断. `workflow_iteration_limit` 在驾驶员/电子结构中存活。 默认图会加入拒绝不可比较的写作;现有的串行/并行调用者会保持他们的行为.

持久性仍然是明确的核心边界延续。 WorkflowDriver不会自动开始检查或提供持久图回放. 没有每个节点恢复,记录回放,或者在远程效应发生后完全恢复.

## 常见问题

### @agentium/harness 是什么？

Agentium 工具、上下文、中件和预设的可编译的带子开发工具包

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

在项目目录运行 npm install @agentium/harness，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@agentium/core（^4\.11\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

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

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

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

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

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

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