# @fabric-harness/sdk 中文文档

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

版本：6\.9\.1
npm 元数据更新时间：2026-11-07T20:17:23.329Z
中文译文更新时间：2026-11-14T07:55:13.399Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：3.4 MB，471 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：5 个
- peer 依赖：ws ^8\.21\.0
- 首次发布：2026-05-05T23:37:19.530Z
- 最新版本发布：2026-11-07T20:17:23.082Z
- 近 30 天下载量：10789（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：81（近 12 个月 81 个）

## 中文简介

用于建造耐用可部署自主代理机的无头型SDK框架.

## 安装

```sh
npm install @fabric-harness/sdk
```

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

## README

# @fabric-harness/sdk (英语)

> 核心 SDK 用于 [技术配置](https://github.com/Fabric-Pro/fabric-harness) ——用于建设耐用可部署自主代理的无头型Script框架.

## 安装

```sh
npm install @fabric-harness/sdk
# or
pnpm add @fabric-harness/sdk
```

## 快开始

### 最小 — 赤色导入, 无头默认( 8行)

```ts
import { defineAgent } from '@fabric-harness/sdk';

export default defineAgent<{ message: string }>({
  name: 'echo',
  triggers: { webhook: true },
  run: async ({ init, input }) => {
    const session = await (await init({ model: 'openai/gpt-5.5' })).session();
    return { reply: await session.prompt<string>(input.message) };
  },
});
```

### 完成 – 相同的导入, 更多字段

### 采用I/O+能力政策+技能(同样导入)

```ts
import { defineAgent, schema } from '@fabric-harness/sdk';

export default defineAgent({
  name: 'triage',
  input: schema.object({ issueNumber: schema.number(), title: schema.string() }),
  output: schema.object({ severity: schema.enum(['low','medium','high']), summary: schema.string() }),
  model: process.env.FABRIC_MODEL,
  run: async ({ init, input }) => {
    const session = await (await init()).session();
    return await session.prompt('Triage and return the typed result.');
  },
});
```

两个表都一样 `init()`, (中文(简体) ), `session.prompt()` 编号 : `skill()` 编号 : `task()` 编号 : `shell()` APIs (英语). 运行时间( E)`stateless`, (中文(简体) ), `inline`,或 `temporal`)是配置于 `init()`。 。 。 .

### 不断演化的活性剂

`createAgent()` 使每次互动。 Hooks允许持久状态改变目前的模式,工具, 技能、子剂、 MCP 连接和沙盒, 不引入另一个构建器 :

```ts
import { createAgent, useModel, usePersistentState, useTool } from '@fabric-harness/sdk';

export default createAgent(() => {
  const [level, setLevel] = usePersistentState('level', 0);
  useModel(level < 2 ? 'anthropic/claude-haiku-4-5' : 'anthropic/claude-sonnet-4-6');
  useTool({ name: 'advance', durable: true, run: async ({ step }) => {
    const receipt = await step.do('advance', async () => ({ advanced: true }));
    setLevel((value) => value + 1);
    return receipt;
  }});
  if (level >= 1) useTool(advancedAnalysis);
  return `Current capability level: ${level}.`;
});
```

## 一个SDK,一个导入

`@fabric-harness/sdk` 是每个人使用的单一导入. `defineAgent({...})` 从光导导入自动注入的无头默认值( e)`runtime: 'stateless'`, (中文(简体) ), `sandbox: 'virtual'`, (中文(简体) ), `loopRuntime: pi-agent-core`, (中文(简体) ), `compaction: { enabled: true }`每张 `init()` 电话 通过将数值传递到 `init()`添加类型 `input`编号 :`output` 计谋, `policy`工艺品 定制商店 遥测技术 这些都是相同的选择 `defineAgent({...})`编号 :`init()` 形状.

在不要求采取隐含行为的情况下,使用临时支持的耐用剂或履约工作量 `@fabric-harness/sdk/strict` ——相同的调用形状,没有注射默认.

运行时间( E)`stateless`, (中文(简体) ), `inline`,或 `temporal`控制持久性和持久性,并配置于 `init()`部署目标`node`, (中文(简体) ), `temporal-worker`, (中文(简体) ), `docker`, (中文(简体) ), `cloudflare`,...)通过 `fh build --target`。 。 。 .

## 盒子里的东西

-   **`init({ model, sandbox, policy, runtime, sessionRuntime, ... })`** 初始化代理运行时间 .
-   **`session.prompt / skill / task / shell`** ——四个代理业务.
-   **`session.mount(mountAt, source, { mode })`** - 挂载 `FilesystemSource` 在运行时间进入沙盒。 默认情况下只读;在挂载下写入在政策层被屏蔽 .
-   **`session.approval.request({ reason, risk?, timeoutMs? })`** ——定制审批闸口. 回返 `true` 批准; 投掷 `APPROVAL_DENIED` 编号 : `APPROVAL_REQUIRED` 拒绝/暂停.
-   **`ApprovalResponse.grant`** ——经核准的持久反应带有呼叫/投入/主要约束 赠款;被拒绝的答复从来不是.
-   **`defineAgent({...})`** ——单人建设者. 赤裸裸的呼唤形状 `@fabric-harness/sdk` 导入和从 `@fabric-harness/sdk/strict`; 您选择的导入是否在运行时注入无头默认值.
-   **`createAgent()` 钩子** 构成持续状态、交付和初步数据、动态资源, 生命周期守护,响应元数据/数据部件,耐用工具步骤,MCP,和子剂.
-   **`defineCommand`** - 约束特权性国家优惠措施(`gh`, (中文(简体) ), `npm`,.)在指挥层有秘密,从不在模型上下文.
-   **`withFilesystemSources`** 编号 : **`session.mount()`** ——将只读内容挂入沙盒的两种方式;代理内置 `grep` 编号 : `glob` 编号 : `read` 工具将其视为普通文件.
-   **`runtime: 'inline' | 'stateless' | 'temporal'`** + 键 **`sessionRuntime`** ——根据坚持不懈的需要选择. 对 `runtime: 'temporal'` 与 `temporalSessionRuntime({...})` 从 `@fabric-harness/temporal` 来通过持久工作流程引导每次会话呼叫.
-   **`CapabilityPolicy`** ——文件系统读取/写出词汇,命令/工具允许-拒绝-认可,以及 `network: { mode, hosts }` 允许列表/拒绝列表. **`policiedFetch(fetch, policy)`** 将任何类似抓取的内容与政策执行相包裹.
-   **示马斯** (单位:千美元)`schema.object`, (中文(简体) ), `schema.enum`——验证输入/输出不设外道.
-   **MCP 磁共振** —— 说 `connectMcpServer` 用于远程工具服务器.
-   **遥测** —— 说 `openTelemetryExporter`, (中文(简体) ), `langfuseExporter`, (中文(简体) ), `consoleTelemetryExporter` 调整 `TelemetrySpan` 形状为 OTel / Langfuse / stdout.

命名的 OpenAI 兼容预设为 `deepseek/<model>` (单位:千美元)`DEEPSEEK_API_KEY`, (中文(简体) ), `moonshot/<model>` 或者说 `kimi/<model>` (单位:千美元)`MOONSHOT_API_KEY`),以及 `xai/<model>` (单位:千美元)`XAI_API_KEY`) (中文(简体) ). 他们 使用直接的提供者端点,从不默默地倒回网关或模拟模型.

## 文档

-   [最小切入点的无头特工](https://harness.techfabric.com/docs/getting-started/headless-mode)
-   [SDK 切入点、运行时间和目标](https://harness.techfabric.com/docs/reference/sdk-entrypoints-runtimes-targets)
-   [运行时间模式](https://harness.techfabric.com/docs/reference/runtime-modes) - 包括直接 `temporalSessionRuntime` API (英语).
-   [活性剂和钩子](https://harness.techfabric.com/docs/building/dynamic-agents)
-   [文件系统源](https://harness.techfabric.com/docs/reference/filesystem-sources) —— 说 `session.mount()` 和源连接器.
-   [政策和核准](https://harness.techfabric.com/docs/reference/policies-approvals) ——能力政策,网络政策,挂载权限,自定义审批.
-   [遥测](https://harness.techfabric.com/docs/reference/telemetry) ——事件,运输,计量.
-   [路线图](https://github.com/Fabric-Pro/fabric-harness/blob/main/docs/ROADMAP.md)
-   [全文参考](https://harness.techfabric.com/docs)

## 许可证

阿帕奇 - 2.0

## 常见问题

### @fabric-harness/sdk 是什么？

用于建造耐用可部署自主代理机的无头型SDK框架\.

### 如何安装 @fabric-harness/sdk？

在项目目录运行 npm install @fabric-harness/sdk，或使用 pnpm add / yarn add / bun add。

### @fabric-harness/sdk 支持 TypeScript 吗？

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

### @fabric-harness/sdk 支持 ESM 还是 CommonJS？

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

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

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

### @fabric-harness/sdk 可以商用吗？

@fabric-harness/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @fabric-harness/sdk 的下载量有多少？

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

### @fabric-harness/sdk 还在维护吗？

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