# @felspar/sdk 中文文档

规范地址：https://npmcn.com/package/%40felspar/sdk/

版本：0\.4\.5
npm 元数据更新时间：2026-11-10T03:12:53.138Z
中文译文更新时间：2026-11-14T14:10:35.616Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：655 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.15\.0
- 运行依赖：1 个
- 首次发布：2026-10-21T22:59:07.127Z
- 最新版本发布：2026-11-10T03:12:52.972Z
- 近 30 天下载量：2268（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

Felspar的客户和行动闸门,企业代理的共享决定系统.

## 安装

```sh
npm install @felspar/sdk
```

也可以使用：`pnpm add @felspar/sdk`、`yarn add @felspar/sdk`、`bun add @felspar/sdk`

## README

# @ felspar/ sdk (英语)

Felspar是企业代理商共同的,版本化的决定系统. 公司认可的含义,证据需要决定,决定本身在发布的"决定包"中一起出行. 特工们要求费尔斯帕做决定,获得他们可以核实的收据,只就费尔斯帕的决定采取行动.

此软件包将代理连接到 Felspar: a [爱娃](https://github.com/vercel/eve) 在两行中连接,一个为主机Felspar API提供的TypeScript客户端,和一个使代理工具在未经核实的Felspar决定的情况下不能行动的动作门. 它运行在节点24或以后, 它唯一的依赖是 `zod`. SDK是一个运输客户端:决定和政策停留在Felspar服务和放行的包上,而SDK不重新执行.

模块 `draft/` 在 API 结算时, 可以在 1.0 之前在小版本之间更改 .

## 安装

```bash
npm install @felspar/sdk
```

## 连接 Eve 代理

单位 `agent/connections/felspar.ts`数字 :

```ts
import { defineMcpClientConnection } from "eve/connections";
import { felsparConnection } from "@felspar/sdk/eve";
export default defineMcpClientConnection(felsparConnection());
```

特工拿到菲尔斯帕的 `list_jobs`, (中文(简体) ), `get_job_requirements`, (中文(简体) ), `get_job_decision` 财务报告和审定财务报表 `check_output` 工具,没有别的。 关键是代理商自己的,在Felspar网页(Workspace → Company 代理商)上创建,并读取自 `FELSPAR_AGENT_KEY` 当 Eve 连接时; 终点是 `FELSPAR_MCP_URL`或生产。 过 `{ url, agentKey, description }` 来推翻他们 这些工具采用的方法是: `get_job_requirements` 说要收集什么和如何收集,每个结果都说下一步要做什么,所以经纪人不需要费尔斯帕的技能或自己的快感.

超过MCP, `get_job_requirements` 财务报告和审定财务报表 `get_job_decision` 默认按紧凑方式回答。 简报 `input` 列出参数和一个简短 `facts` 以工作本身的问题为例。 裁决保留了特工的行为 `executionObjectId`,满 `receipt`,则 `context` 胶囊和 `explanation.evidenceFreshUntil`,这是动作门记录和验证. `detail: "full"` 返回 REST 简介或结果不变。 代理发送未执行 ID: 呼叫 `get_job_decision` 在同一小时内再次提出同样的论点,将已经作出的决定退回 `blocked` 表示第一通电话仍在运行. 见 [MCP工具](https://docs.felspar.ai/reference/mcp-tools)。 。 。 .

## 主机客户端

```ts
import { createHostedFelsparClient } from "@felspar/sdk/draft/hosted-client";

const felspar = createHostedFelsparClient({
  origin: "https://api.felspar.ai",
  agentKey: process.env.FELSPAR_AGENT_KEY,
});

// The jobs this agent key may run, by ID.
const { jobs } = await felspar.listJobs();

// What the job needs (questions, evidence rules, outcomes and their outputs),
// on the release Felspar runs for this key now.
const job = await felspar.describeCurrentJob("route-support-ticket");
const releaseId = job.release.releaseId;

// Facts in, decision out. The release pin comes from the job description.
const response = await felspar.resolveFacts(releaseId, {
  jobId: "route-support-ticket",
  executionId: crypto.randomUUID(),
  entityId: "48213",
  facts: {
    request_type: {
      text: "I was charged twice for my March invoice.",
      source: { class: "ticket-thread", id: "48213", observedAt: new Date().toISOString() },
    },
  },
});

if (response.status === "ready") {
  console.log(response.result?.outcome, response.result?.receipt);
}
```

### 一个电话: `decide`

自兹 `0.4.4`;规则、下一步、交接单词、收据和公开的事实 `0.4.5`。 。 。 .

当同样的证据每次到达时(一个编码代理的工具呼叫及其更改记录,一张支持票及其账户记录),按种类给每块贴上标签,让费尔斯帕在工作的问题下存档:

```ts
const decision = await felspar.decide({
  job: "gate-deploys",
  case: "toolu_01ABC", // the case's ID; leave it out where the job derives its IDs
  evidence: [
    { kind: "tool-call", toolCall: { name: "Bash", input: { command: "kubectl apply -f deploy/prod.yaml" } } },
    { kind: "change-record", id: "CHG-1042", text: "CHG-1042: approved by Ana Ruiz; production" },
  ],
  timeoutMs: 10_000, // the default; keep it inside your caller's own timeout
});
// { action: "allow" | "flag" | "block", reason, rule, nextStep, missing, escalation,
//   resultId, receiptUrl, open, toProceed, outcome, receipt }
if (decision.action === "block") {
  console.error(decision.reason, decision.nextStep, decision.toProceed);
}
```

`decide` 发送一个请求,没有执行ID或放行: Felspar使用代理的放行(Lasters或被绑),同一小时的同名呼叫返回同一个决定. 一个工具呼叫是 `toolCall` 正如特工的运行时间报告的那样 Felspar读了. `action` 这是做什么。 没错 `allow` 或者说 `flag` 只有在费尔斯帕决定一个结果 意味着,和 `block` 对于其他一切:阻碍的结果、缺少证据、拒绝、内部无答案 `timeoutMs`,或者没有连接。 所以,代码只作用于 `action` 未关闭 . `reason` 是政策所引用的规则,或者,用简单的话说,为什么没有决定. `nextStep` 政策是现在要做什么, `escalation.text` 谁从这里拿,和 `resultId` 财务报告和审定财务报表 `receiptUrl` 裁决的收据。 当费尔斯帕无法决定时, `open` 列出每个无法用平话解决的事实 `label`,以及 `toProceed` 说什么证据可以解决它。 派一个老费尔斯帕不回来 `null` 或为空. `decide` 永远不要扔, 并在最后期限内重复一次 当菲尔斯帕忙着,或者同一个电话仍在决定。 过 `shadow: true` 费尔斯帕记录下来 每个 `kind` 必须是工作描述列表 在问题接受的来源.

`describeJob(releaseId, jobId)` 描述一个你已经知道的释放, 比如一个你钉住.

事实可以直接来自一种记录系统,在两者之间没有代理人:将每个问题的证据作为消息来源自己的话发去(......)`text`,例如票房或账号记录的"计划:业务(月刊)",与票出处相通(出处相通)`source.class`, (中文(简体) ), `source.id`, (中文(简体) ), `source.observedAt`) (中文(简体) ). Felspar将这些单词归为回答选择和是/否问题;一个赤裸的标签,例如: `{ value: "business" }` 拒绝使用 `label_needs_mapping`因为释放的问题决定了这些词的含义。 数字和日期问题按键 `{ value }` (日期为: `YYYY-MM-DD`) (中文(简体) ). 只有工作本身的问题键被接受( E)`unknown_question` (否则).

一个人给代理人的言语(从电话中发出的一行信息)也是证据:按给与的发送 `source: { class, manual: true, locator }`名称 `locator` 他们的来源,没有 `id` 或者说 `observedAt`; Felspar 邮票收到时间,结果和收发情况将它们列在 `manualFacts`. 其描述包含 `manualFacts: { allowed: false }` 拒绝`manual_facts_refused`:引用源记录本身.

`verifyReceipt(executionObjectId, { receipt, expectedReceiptDigest, deliveredCapsule })` 要求费尔斯帕重播一个决定并比较其收到,以及 `checkOutput(job, { executionId, text, output? })` 检查您决定的文本( e)`readOutputCheck(job, checkId)` 读回一张支票).

如何识别案件来自该工作的描述(`identity`: 发送 `entityId` 为记录自己的身份(`provided`, (中文(简体) ), `identity` 字段值( r)`fields`),或无(`content`,以及第一个决定 `issued` 任务。 结果 `case` 给案件 `id` 财务报告和审定财务报表 `mode`; 发送 `case.id` 作为 `entityId` 以后对同一案件的判决 输入结果(`FelsparJobResult`: `case`, (中文(简体) ), `subject` 联合国 `related` 记录, `escalation` (单位:千美元)`id`, (中文(简体) ), `trigger`, (中文(简体) ), `why`和 `missing` 为了一个缺口.

拒绝的请求 `FelsparRequestError` 与 HTTP 连接 `status` 服务 `refusal` (数量) `error` 代码,其中有一个a `fix` (单位:千美元) `recovery` 联 合 国 `fix_input`, (中文(简体) ), `retry` 或者说 `escalate`,以及任意 `escalation` 名称,例如: `attempt_limit_reached`) (中文(简体) ).

## 行动门

大门坐落在一个工具前,它的行为,例如写出电子邮件草稿或回答罚单. 只有在允许调用字段时,才允许调用,调用的内容是本会中决定的一个案例Felspar,Felspar重新核实决定的收受,决定的结果允许该工具. 任何错误,以及任何未知或含糊不清的东西,都否认.

```ts
import {
  createActionGate,
  felsparJobDescriber,
  felsparOutputCheckVerifier,
  felsparVerifier,
} from "@felspar/sdk/draft/action-gate";

const felspar = { origin: "https://api.felspar.ai", agentKey };
const gate = createActionGate({
  job: "route-support-ticket",
  decisionTool: "felspar__get_job_decision", // exact tool names in your runtime
  outputCheckTool: "felspar__check_output",
  tools: {
    helpdesk__reply: {
      writes: "billing-team-reply",
      entity: { field: "ticketId" },
      fields: ["ticketId", "body"],
      outputCheck: { fields: ["body"] },
    },
  },
  verify: felsparVerifier(felspar),
  describe: felsparJobDescriber(felspar),
  verifyOutputCheck: felsparOutputCheckVerifier(felspar),
});
```

一个工具可能做的来自于释放的包,而不是出自大门的配置:

-   `writes` 名称工具所写的输出, 以其在包中的 ID 。 只有当发布的职务说明列出了结果Felspar的回放报告下的输出时,才允许调用. (规则可以规定 `outcomes`,则列出结果标识;确切地说,两者之一。 )
-   哪个案子的电话来自被解职的主体和身份 决定记录在 `case.id` Felspar 的结果名称( 所以是发送否的代理 `entity_id`,对于一个发行,字段或内容工作,仍然得到一个),而费尔斯帕尔的回放必须命名同一个案例ID和模式. 默认 :
    -   对于一个被提供对象的不敏感案例的ID,例如网页域(或无主题的发布),每个收件人的电子邮件域必须属于一个决定的Felspar公司;一个不是公司域的决定ID不允许收件人,所以给这样的规则一个实体域;
    -   对于其他任何工作, 调用是关于此工作在会话中决定的一个案件; 对于几个案件, 调用会被拒绝, 直到规则指定一个字段.
-   `entity: { field }` 覆盖:输入字段必须持有案件的ID,记录本身的ID(如票证)或 `case.id` Felspar发布或衍生出,修剪并配对主体的匹配规则(除非主体对大小写不敏感;没有主体, `HC-1201` 财务报告和审定财务报表 `hc-1201` (见A/CN.9/WG.III/WP.96,第2段)。 接收者则不与案件挂钩,因此,一个能够解决任何人问题的工具也应加以限制(`testRecipients`,或工具自己的设置).
-   `outputCheck` 要求Felspar通过该呼吁为该决定发出的文本(`check_output`; 与 `writes`用于输出.

拒绝是 `{ allow: false, reason, escalate?, escalation? }`。 。 。 . `escalate` 是公司的下一步,引自所发布的描述:结果不允许工具时,结果的下一步,或者无所决定时该怎么办. 对于缺失或失败的输出检查,是固定指令来修正什么 `check_output` 标记和检查再次. `escalation` 政策名称是: `{ id, trigger, why }`,随着费尔斯帕尔重播结果的ID(或工作未解决的路径)和 `why` 引自该版。 释放时两人都缺席. 下方的每个适配器都带着理由向模型显示.

然后连接大门到你的代理框架。 工具名必须与运行时间报告完全匹配 .

### 爱娃

```ts
import { felsparDecisionEvents, felsparGate } from "@felspar/sdk/eve";

// On the connection whose tools act:
approval: felsparGate(gate),
// And in a hook that records Felspar's decisions and output checks:
export default defineHook({ events: felsparDecisionEvents(gate) });
```

### 克劳德探员SDK

```ts
import { felsparHooks } from "@felspar/sdk/draft/action-gate/claude-agent-sdk";

// Tool names are mcp__<server>__<tool>.
for await (const message of query({ prompt, options: { hooks: felsparHooks(gate) } })) {
  // ...
}
```

### OpenAI 代理服务器 SDK

```ts
import {
  felsparDecisionOutputGuardrail,
  felsparToolInputGuardrail,
} from "@felspar/sdk/draft/action-gate/openai-agents";

// sessionOf must return an ID unique to the conversation.
const sessionOf = (runContext) => (runContext.context as { conversationId: string }).conversationId;
// On the MCP server whose tools act:
toolInputGuardrails: [felsparToolInputGuardrail(gate, { sessionOf })],
// On Felspar's MCP server:
toolOutputGuardrails: [felsparDecisionOutputGuardrail(gate, { sessionOf })],
```

在代理框架之外, `checkAction({ rules, toolName, input, decisions, verify, describe })` 返回同一判决.

对于生产行动,设定 `environment: "production"` 门规则; 使用 `"staging"` 为中转门。 此选项在 `0.4.3`A级 配置的门否认其他或缺失环境,包括中转决定 他们的释放后来得到了促进。 暗示它保留了现有的行为 没有环境限制。 保留设置主机; 自定义验证器 必须返回环境 Felspar确认。 A 类 `releases` 单针不会 建立决定的环境.

一份Felspar收据记录了Felspar从提供的证据中裁定的内容。 它不是事实、法律或安全证明,通过的产出检查意味着文本遵循已发布的规则,而不是真实或批准发送.

## 实例

[felspar 实例](https://github.com/orchidautomation/felspar-examples) 拥有完整的项目:一个Eve代理,一个在动作门后有电子邮件草稿的同一代理,以及一个在没有代理的情况下得到决定的脚本.

## 文档

完整文档: [(原始内容存档于2017-09-28) (英语). docs.felspar.ai](https://docs.felspar.ai/)。 。 。 .

## 许可证

阿帕奇 - 2.0

### 为人们绘制的决策图

主机客户的 `getReleaseGraph(releaseId)`, (中文(简体) ), `getProposalGraph(proposalId)` 财务报告和审定财务报表 `getDecisionGraph(executionObjectId)` 读取卡通美人鱼图 释放/物质针和仪表板链接。 这些检查方法要求: ; 拒绝代理密钥。 决定 图表复制其原始发行时保存的收据。 检查 `status` 在此之前 使用 `mermaid`: 没有历史不是推断路径 。 显示返回的 来源不变.

使用 `getReleaseDiagram`, (中文(简体) ), `getProposalDiagram` 或者说 `getDecisionDiagram` 联 合 国 简明概览。 每个都接受 `{ detail: "overview" | "full" }`;决定 帮助者也接受 `{ view: "run" | "release" }`检查 `availability`显示 `mermaid` 和全面结果 `overview`,并提议 原图 `canonical`。原始的图表助手不变.

## 常见问题

### @felspar/sdk 是什么？

Felspar的客户和行动闸门,企业代理的共享决定系统\.

### 如何安装 @felspar/sdk？

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

### @felspar/sdk 支持 TypeScript 吗？

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

### @felspar/sdk 支持 ESM 还是 CommonJS？

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

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

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

### @felspar/sdk 可以商用吗？

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

### @felspar/sdk 的下载量有多少？

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

### @felspar/sdk 还在维护吗？

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