# @deedglass/sdk 中文文档

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

版本：0\.15\.0
npm 元数据更新时间：2026-10-28T08:49:06.693Z
中文译文更新时间：2026-11-12T10:14:17.675Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：229 kB，84 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12
- 运行依赖：0 个
- peer 依赖：ai \>=7 \<8，@openai/agents \>=0\.18 \<1，@langchain/core \>=1\.2 \<2，@anthropic-ai/claude-agent-sdk \>=0\.3 \<0\.4
- 首次发布：2026-10-15T16:01:33.629Z
- 最新版本发布：2026-10-28T08:49:06.256Z
- 近 30 天下载量：2596（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

把地德格拉斯放在你经纪人的工具前: 政策决定,人们批准,每一次通话都被封为契约,你可以检查下线.

## 安装

```sh
npm install @deedglass/sdk
```

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

## README

# @ diedglass/ sdk (英语)

把德德格拉斯放在你经纪人的工具前 每一次通话都是由政策决定的,当规则规定时,由一个人批准,封为契约,你可以检查下线.

```ts
import { Deedglass, wrapTool } from '@deedglass/sdk';

const dg = new Deedglass();            // reads DEEDGLASS_API_KEY and DEEDGLASS_SERVER
const refund = wrapTool(refundCustomer, { client: dg, tool: 'billing.refund_customer' });
await refund({ customer: 'cus_123', amount: 2000 });   // runs only if policy allows it
```

与Vercel AI SDK,OpenAI代理SDK,LangChain.js和克洛德代理SDK合作. 没有运行时间依赖 。 节点22.12+, Bun, Deno和边缘跑道.

**它没有做什么:** 它不保存您的功能( 它决定它是否运行), 结果您的代码报告被记录为已报告( L0) 。 需要L1或L2时使用Dedglass连接器.

## 安装

```sh
npm install @deedglass/sdk
```

设定 `DEEDGLASS_API_KEY` (代理密钥, `dg_test_…` 或者说 `dg_live_…`,来自Console QQ代理)和 `DEEDGLASS_SERVER` (默认) `http://127.0.0.1:8080`) (中文(简体) ). 一揽子措施是无害环境管理;在22.12节点和较新的节点上, `require('@deedglass/sdk')` 还行.

## 三个用法

**1\. 本人的职能: `wrapTool` (代理模式).** Dedglass 决定;您的功能只在动作被授权后运行,最多一次;其结果被报告和封存.

```ts
const refund = wrapTool(refundCustomer, {
  client: dg,
  tool: 'billing.refund_customer',
  onPending: 'throw',          // or 'wait' for a person to decide
  failureMeans: 'unknown',     // a thrown error means "it may have run" (the default)
});
```

-   拒绝掷出 `PolicyDeniedError` 与保单的句子。 你的职能从来没有运行.
-   等待批准的掷出 `ApprovalPendingError` (与 `approvalId` 财务报告和审定财务报表 `expiresAt`) (中文(简体) ). 在一个人批准你运行一次之后,用同样的论据再次召唤;它不再问了.
-   如果您的函数抛出, 证书上写着“ 它可能已经运行 ” `ToolExecutionError` 原文为: `cause`。通过 `failureMeans: 'not_applied'` 仅当函数在任何副作用之前失败时.

**2\. 连接工具: `act` (出道模式).** 戴德格拉斯用连接器的证书来运行工具,它永远不会离开.

```ts
const a = await dg.act('stripe.create_refund', { charge: 'ch_3QxZ8f2L', amount: 2000 });
a.status;          // 'executed' · 'pending_approval' · 'failed'
a.witness?.verdict; // 'VERIFIED' at L1: Stripe's own record was read back
a.deed;            // 'deed_01j9…'
```

运行失败的工具返回 `status: 'failed'` 行动已经发生 所以也并非例外.

**3\. 检查下线的契约: `@deedglass/sdk/verify`。 。 。 .** 不需要密钥, 答案与 `deedglass verify`。 。 。 .

```ts
import { fetchKeys, verifyDeeds, splitLines } from '@deedglass/sdk/verify';
const { keys } = await fetchKeys('https://deedglass.example/.well-known/deedglass/keys.json');
const report = await verifyDeeds(splitLines(bytes), keys, { keysPinned: true });
report.result;     // 'valid' · 'invalid' · 'cannot_determine'
```

## 框架

| 导入 | 打开工具( 代理) | 连接工具(出入口) |
| --- | --- | --- |
| `@deedglass/sdk/ai-sdk` | `governTools(tools, { client })` | `deedglassTools(client)` |
| `@deedglass/sdk/openai-agents` | `governTool(tool, { client })` | `deedglassTools(client)` |
| `@deedglass/sdk/langchain` | `governTool(tool, { client })` | `deedglassTools(client)` |
| `@deedglass/sdk/claude-agent-sdk` | `deedglassHooks({ client })`, (中文(简体) ), `governSdkTool(def, { client })` | `deedglassMcpServer(client)` |

适配器默认情况下将拒绝执行或待执行的判决退回模型(`onDenied: 'message'`, (中文(简体) ), `onPending: 'message'`),因为框架反馈工具输出回模型,而抛出会结束一些运行.

## 错误

每个错误都是 `DeedglassError` 与 `type`, (中文(简体) ), `code`, (中文(简体) ), `message` (服务器的,逐字记录), `param`, (中文(简体) ), `status`, (中文(简体) ), `requestId` 财务报告和审定财务报表 `docUrl`; 拒绝带封口 `action`启用 `isDeedglassError(e)`;它的工作跨越包的复制.

| 类 | 何时 |
| --- | --- |
| `AuthenticationError` | `invalid_api_key`, (中文(简体) ), `api_key_revoked`, (中文(简体) ), `api_key_expired` |
| `PermissionDeniedError` | `agent_stopped`, (中文(简体) ), `org_stopped`, (中文(简体) ), `insufficient_scope`, (中文(简体) ), `intent_*` |
| `PolicyDeniedError` | `policy_denied` |
| `BudgetExceededError` | 429个 `budget_exceeded` (从来没有再试) |
| `RateLimitError` | 429个 `rate_limited`,在复试后 |
| `InvalidRequestError` | `validation_failed`, (中文(简体) ), `not_found`, (中文(简体) ), `conflict`, (中文(简体) ), `idempotency_conflict` |
| `APIError` | 5 (简体中文) |
| `ConnectionError`, (中文(简体) ), `TimeoutError` | 网络; 超时表示动作可能仍在运行 |
| `ApprovalPendingError`, (中文(简体) ), `ToolExecutionError` | `wrapTool` |

## 失职和重审

每个POST都带一个 `Idempotency-Key`,每次重试都使用同样的一个,所以服务器从未运行过两次工具. 网络错误, 408, 429 `rate_limited`, 500, 502, 503 和 504 默认情况下两次重审, 以指数反射, 以纪念 `Retry-After` 最多10 s 永远不要过你的 `signal` 或者说 `timeoutMs` (每项请求30 s).

## 签名意图

给客户端一个 Ed25519 键(`deedglass agent intent keygen` 写一个),每通电话都与 `deedglass.intent/1`数字 :

```ts
const dg = new Deedglass({ intentKey: { privateKeyPem: process.env.DEEDGLASS_INTENT_KEY! } });
```

`signIntent`, (中文(简体) ), `argsDigest`, (中文(简体) ), `intentKid` 财务报告和审定财务报表 `generateIntentKey` 用于自用。 2^53 - 1 参数中的整数被拒绝: 把它们作为字符串发送 .

## 运行时间

节点22.12和较新, Bun, Deno, Cloudflare工人和Vercel Edge (Ed25519 in WebCrypto). 客户端拒绝从浏览器页面开始,因为代理密钥是秘密:从您的服务器上呼叫Deedglass. 过 `dangerouslyAllowBrowser: true` 只有你接受这种风险. `@deedglass/sdk/verify` 到处跑.

## 它不会做什么

-   `wrapTool` 决定您的代码是否运行; 它不是沙盒 它做什么.
-   代理模式结果为L0(对接报告). 独立的L1/L2检查需要戴德格拉斯连接器.
-   Claude钩子只看到通过钩子的SDK特工路线的工具.
-   离线核查检查封条和链条,而不是动作是否明智.

阿帕奇2.0 (英语).

## 常见问题

### @deedglass/sdk 是什么？

把地德格拉斯放在你经纪人的工具前: 政策决定,人们批准,每一次通话都被封为契约,你可以检查下线\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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