# @armoriq/sdk-dev 中文文档

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

版本：0\.8\.23
npm 元数据更新时间：2026-10-21T06:09:12.778Z
中文译文更新时间：2026-11-06T19:55:09.336Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.5 MB，231 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：^18\.19\.0 \|\| \>=20\.6\.0
- 运行依赖：11 个
- peer 依赖：openai \>=4\.0\.0，@anthropic-ai/sdk \>=0\.51\.0
- 首次发布：2026-04-13T17:42:22.082Z
- 最新版本发布：2026-10-21T06:09:12.575Z
- 近 30 天下载量：3253（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 53 个）

## 中文简介

ArmorIQ SDK - 建立安全的AI代理,并进行加密意图验证.

## 安装

```sh
npm install @armoriq/sdk-dev
```

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

## README

# 装甲IQ SDK (TypeScript)

**建立加密意图验证的安全AI代理.**

ArmorIQ SDK使开发者能够构建内置安全性和可审计性的AI代理. 只有一个API键 - 没有云的复杂性.

* * *

## 为什么是装甲部队?

-   **简单** - 只有一个API键,没有云证明
-   **安全** - 对每项行动进行加密核查
-   **应审计** - 完整的行刑线索
-   **快点** - 五分钟后开始

* * *

## 安装

```bash
npm install @armoriq/sdk
# or
yarn add @armoriq/sdk
```

* * *

## 快速启动

### 1\. 获取您的 API 密钥

访问 [(原始内容存档于2018-03-25) (英语). armariq.ai](https://platform.armoriq.ai/) 生成您的 API 密钥.

### 2\. 客户初始化

```typescript
import { ArmorIQClient } from '@armoriq/sdk';

const client = new ArmorIQClient({
  apiKey: 'ak_your_key_here',
  userId: 'your-user-id',
  agentId: 'your-agent-id',
});
```

### 3\. 抓住你的计划

```typescript
const plan = {
  goal: 'Get weather forecast',
  steps: [
    {
      action: 'get_weather',
      tool: 'weather_api',
      mcp: 'weather-mcp',
      inputs: { city: 'Boston' },
    },
  ],
};

const planCapture = client.capturePlan('gpt-4', "What's the weather in Boston?", plan);
```

### 4\. 获得意向托肯

```typescript
const token = await client.getIntentToken(planCapture);
```

### 5\. 启动行动

```typescript
const result = await client.invoke('weather-mcp', 'get_weather', token, {
  city: 'Boston',
});

console.log(result);
```

* * *

## 环境变量

```bash
# Required
ARMORIQ_API_KEY=ak_your_key_here
USER_ID=your-user-id
AGENT_ID=your-agent-id

# Optional
ARMORIQ_ENV=production  # or 'local' for local development
CONTEXT_ID=default
ARMORIQ_BACKEND_URL=https://api.armoriq.ai  # read before BACKEND_ENDPOINT, by the CLI and the client
PROXY_ENDPOINT=https://proxy.armoriq.ai
IAP_ENDPOINT=https://iap.armoriq.ai
```

还没有, `PROXY_ENDPOINT` 财务报告和审定财务报表 `IAP_ENDPOINT` 跟随后端:一种生产, 中继或本地后端得到环境的代理和IAP. 任何其他 后端需要两个设置, 或者第一个使用失败的调用 缺少变量.

* * *

## 原生的 OpenTeleometry 可观察性

0.7.0版本每会话有一棵原生的OpenTeleometry横跨树. 它支持 完全有三个出口选择。 组织政策仍然支配着各种选择; 当可观察性被关闭或政策权威不存在时, SDK 不 出口遥测和代理执行仍在继续.

### 1\. 装甲运兵车

ArmorIQ OTLP是默认的. 不需要端点配置 .

```typescript
const session = client.startSession({ mode: 'sdk' });
```

### 2\. 一般外部OTLP终点

通过选项或标准使用符合标准的 HTTP/ protobuf 端点 OpenTeleometry环境变量.

```typescript
const client = new ArmorIQClient({
  apiKey: 'ak_your_key_here',
  observability: {
    exporter: 'external',
    endpoint: 'https://collector.example.com/v1/traces',
    headers: { Authorization: 'Bearer token' },
  },
});
```

```bash
OTEL_SERVICE_NAME=my-agent
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://observability.example.com/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20token,x-tenant-id=my-tenant
```

你可以提供一个底端。 SDK 附件 `/v1/traces` 仅限 此基准窗体 :

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20token
```

追踪特定设置优先于一般设置:

```text
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT > OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_EXPORTER_OTLP_TRACES_HEADERS  > OTEL_EXPORTER_OTLP_HEADERS
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL > OTEL_EXPORTER_OTLP_PROTOCOL
OTEL_EXPORTER_OTLP_TRACES_TIMEOUT  > OTEL_EXPORTER_OTLP_TIMEOUT
```

### 3\. 呼叫者拥有的追踪器供应商

当应用程序拥有提供者时, 通过您自己的 OpenTelemetry 跟踪器提供者 生命周期和出口商设置.

```typescript
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';

const provider = new NodeTracerProvider();
const session = client.startSession({
  observability: { exporter: 'provider', tracerProvider: provider },
});
```

仅 `http/protobuf` 支持SDK管理的外部出口商。 (原始内容存档于2018-03-26). GRPC,, OTLP/JSON,压缩,HTTP代理配置,和mTLS配置是 未经该出口商支持. 在需要时将这些特性设置在 OpenTeleometry Collection 上. 这个 出口者失败打开:远程停用、反应不良或超时永远不会改变 代理请求的结果. `content-type` 由于 SDK总是发送 `application/x-protobuf`。 。 。 .

在第一次外部追踪之前,SDK最多等待1.4秒 组织政策权威。 此一次性约束可防止未经授权的数据 从到达第三方。 如果在约束范围内没有权力, 外部遥测在那个会话中仍然被禁用,代理机还在继续.

一个SDK运行时间有一个出口选择. 用于扇出到AmorIQ和外部 工具,使用 OpenTeleometry Collection 来引导允许的痕迹.

### Langfuse 实例

Langfuse是一个与OTLP兼容的目的地. 配置其 OTLP 端点和 环境中的标准标题; 不添加 Langfuse 特定的运行时代码 给您的代理人 :

```bash
OTEL_SERVICE_NAME=my-agent
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://cloud.langfuse.com/api/public/otel/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Basic%20BASE64_PUBLIC_KEY_COLON_SECRET_KEY,x-langfuse-ingestion-version=4
```

对于另一个供应商,使用该供应商记录的OTLP跟踪终点和 头. SDK不推断出销售商的URL,证书,或私有字段.

### 外部输出什么

外部OTLP输出总是包括痕量分级,稳定跨度名称, 服务身份、支持GenAI模型和符号使用属性以及安全 资源属性。 API钥匙、政策有效载荷、私人ArmorIQ身份证以及 任意用户元数据永远不会导出到外部目标.

默认时不包含快速内容、输出和工具参数/结果. 只有在该组织的 政策租赁既允许获取内容,也允许获取外部内容 有效的捕获模式是 `enhanced` 或者说 `debug` - 其他组合 (包括目前不具有权威性的政策获取) 他们。 默认情况下, 不要依赖外部导出为无内容 组织运行这些赠款并启用抓取模式; 检查您 组织的可观察性政策,如果这保证了你的重要性.

支持的安全资源属性为:

```bash
OTEL_SERVICE_NAME=my-agent
OTEL_RESOURCE_ATTRIBUTES=service.namespace=education,deployment.environment.name=staging
```

不在资源属性中设置秘密或用户内容. 不支持的资源 属性、畸形属性和看起来像电话号码的值, SSN,或付款卡号码在导出前被忽略.

### 抓取模式和每次会议选择退出

捕捉模式是准确的 `off`, (中文(简体) ), `metadata`, (中文(简体) ), `enhanced`,以及 `debug`。 。 。 . 选择以 `ARMORIQ_OTEL_CAPTURE_MODE` 或者说 `observability.captureMode`;组织政策只能缩小.

串流聊天请求包括 `stream_options: { include_usage: true }` 以 默认( e)`otel.streamUsage`, (中文(简体) ), `ARMORIQ_OTEL_STREAM_USAGE`, 默认值) 使用方式是隐藏在呼叫者身上的只使用块。 设定 `ARMORIQ_OTEL_STREAM_USAGE=0` (或 `observability.streamUsage: false`当a 网关拒绝 `stream_options` 或者生水流必须保持不动 一个 明确 `stream_options` 在请求中永远不变.

```typescript
const noTelemetrySession = client.startSession({
  observability: { enabled: false },
});
```

### 转写符号用途

托肯用法被存储在每个会话,模型,协调世界时的日期和协调世界时小时. 每个消息 以时间戳计算 通过会话的原生OTel桥 当你记录笔录使用时,模型符号就会变成 `gen_ai.chat` 在同一个跟踪.

```typescript
await client.captureTranscriptTokens({
  transcriptPath: '/tmp/transcript.jsonl',
  product: 'armorclaude',
  sessionId: session.sessionId,
  otel: session.otelSession,
});
```

将克劳德代码会话 包括其子代理记录, 逐个小时总结一下,送一个过来 `recordTokenUsage` 每小时打电话. `usageDate` (单位:千美元)`YYYY-MM-DD`和 `usageHour` 需要(0-23);无 有效对返回 `{ ok: false, reason }` 并张贴什么.

```typescript
import { summarizeSessionUsageByHour } from '@armoriq/sdk';

const seen = new Set<string>();
const { hours, repo } = summarizeSessionUsageByHour(mainTranscriptPath, { seen });
for (const { usageDate, usageHour, entries } of hours) {
  await client.recordTokenUsage({
    product: 'armorclaude',
    sessionId,
    usageDate,
    usageHour,
    entries,
    repo,
  });
}
```

每个员额都取代该会话的行,型号,日期,小时和设备. 份额 一个 `seen` 设定跨会话, 所以历史复制到一个要塞会话计数中 一次 一次吗.

### 0.7.0 断开更改

先前的管道选择器、JSON记录器和托运人API、记录器手柄, 计划和微量摘要出口,以及 `defaultObservabilityConfig` 被删除. 使用 `session.otelSession` 给土生土长。 参见0.7.0分折换附注 内 [变动情况](https://npmcn.com/package/%40armoriq/sdk-dev/CHANGELOG.md) 用于完整的被移除的公共表面.

* * *

## 高级使用

### 代表团

```typescript
import * as crypto from 'crypto';

// Generate delegate keypair
const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
const pubKeyHex = publicKey.export({ type: 'spki', format: 'der' }).toString('hex');

const delegation = await client.delegate(token, pubKeyHex, 1800);
console.log(`Delegated token: ${delegation.delegatedToken.tokenId}`);
```

### 自定义代理端点

```typescript
const client = new ArmorIQClient({
  apiKey: 'ak_your_key_here',
  userId: 'user-123',
  agentId: 'agent-456',
  proxyEndpoints: {
    'weather-mcp': 'https://weather-proxy.example.com',
    'finance-mcp': 'https://finance-proxy.example.com',
  },
});
```

### 处理错误

```typescript
import {
  InvalidTokenException,
  MCPInvocationException,
  PolicyBlockedException,
  TokenExpiredException,
} from '@armoriq/sdk';

try {
  const result = await client.invoke('weather-mcp', 'get_weather', token, { city: 'Boston' });
} catch (error) {
  if (error instanceof TokenExpiredException) {
    console.error('Token expired, please get a new one');
  } else if (error instanceof PolicyBlockedException) {
    // The backend refuses a step outside the anchored plan, or one a policy blocks.
    console.error('Blocked:', error.reason);
  } else if (error instanceof MCPInvocationException) {
    console.error('MCP invocation failed:', error.message);
  }
}
```

* * *

## API 参考

### `ArmorIQClient`

#### 构造选项

```typescript
interface SDKConfig {
  apiKey: string; // Required: Your API key
  userId: string; // Required: User identifier
  agentId: string; // Required: Agent identifier
  contextId?: string; // Optional: Context identifier (default: 'default')
  useProduction?: boolean; // Optional: Use production endpoints (default: true)
  iapEndpoint?: string; // Optional: Override IAP endpoint
  proxyEndpoint?: string; // Optional: Override proxy endpoint
  backendEndpoint?: string; // Optional: Override backend endpoint
  proxyEndpoints?: Record<string, string>; // Optional: MCP-specific proxies
  timeout?: number; // Optional: Request timeout in ms (default: 30000)
  maxRetries?: number; // Optional: Max retry attempts (default: 3)
  verifySsl?: boolean; // Optional: Verify SSL (default: true)
}
```

#### 方法

-   `capturePlan(llm, prompt, plan, metadata?)` - 获取一个执行计划
-   `getIntentToken(planCapture, policy?, validitySeconds?)` - 拿个签名的意向书
-   `invoke(mcp, action, intentToken, params?, userEmail?)` - 启动MCP行动
-   `delegate(intentToken, delegatePublicKey, validitySeconds?, allowedActions?, targetAgent?, subtask?)` - 另一名代理人的代表
-   `verifyToken(intentToken)` - 在当地验证一个标志
-   `close()` - 清理资源

* * *

## 文档

完整文件,访问 [(原始内容存档于2017-09-26). docs.armoriq.ai](https://docs.armoriq.ai/)

适用于原生框架适配器版本、生命周期钩、回调链和 已知界限,参见 [框架相容性矩阵](https://npmcn.com/package/%40armoriq/sdk-dev/docs/integrations/compatibility-matrix.md)。 。 。 .

仅限 0.7.0 的放出序列,见 [发布运行本](https://npmcn.com/package/%40armoriq/sdk-dev/docs/release-0.7.0-otlp-only.md)。 。 。 .

* * *

## 链接

-   [军械库](https://armoriq.ai/)
-   [(原始内容存档于2017-09-26). docs.armoriq.ai](https://docs.armoriq.ai/)
-   [(原始内容存档于2018-03-25) (英语). armariq.ai](https://platform.armoriq.ai/)

* * *

## 许可证

麻省理工学院执照 - 看 [自由主义](https://npmcn.com/package/%40armoriq/sdk-dev/LICENSE) 详细文件.

## 常见问题

### @armoriq/sdk-dev 是什么？

ArmorIQ SDK - 建立安全的AI代理,并进行加密意图验证\.

### 如何安装 @armoriq/sdk-dev？

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

### @armoriq/sdk-dev 支持 TypeScript 吗？

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

### @armoriq/sdk-dev 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

### @armoriq/sdk-dev 可以商用吗？

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

### @armoriq/sdk-dev 的下载量有多少？

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

### @armoriq/sdk-dev 还在维护吗？

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