# @atlasauth/pca-openai-agents 中文文档

规范地址：https://npmcn.com/package/%40atlasauth/pca-openai-agents/

版本：0\.4\.3
npm 元数据更新时间：2026-10-27T19:47:19.732Z
中文译文更新时间：2026-11-08T11:15:37.204Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40atlasauth/pca-openai-agents
原文对照：https://npmcn.com/package/%40atlasauth/pca-openai-agents/?lang=original
项目主页：https://github.com/Atlas-Authorization/pca#readme
源码仓库：https://github.com/Atlas-Authorization/pca

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

- 包体积（解压后）：49.2 kB，6 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-10-08T14:45:02.540Z
- 最新版本发布：2026-10-27T19:47:19.491Z
- 近 30 天下载量：1793（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

OpenAI Agents SDK (@openai/ agents) PCA的守护者: guardrail + 工具-执行钩,所以每个代理工具呼叫都是由证明-携带+政策-加分.

## 安装

```sh
npm install @atlasauth/pca-openai-agents
```

也可以使用：`pnpm add @atlasauth/pca-openai-agents`、`yarn add @atlasauth/pca-openai-agents`、`bun add @atlasauth/pca-openai-agents`

## README

# @atlasauth/pca-openai-代理服务器

OpenAI代理SDK的警卫(`@openai/agents`使得每个代理工具都称为"证明携带". `withPcaTool` 将工具包成这样 `execute` 首先需要一个 PCActn( 从运行上下文读取) , 用 PPC 核心验证它, 然后只运行原始工具; 在任何失败时, 它都会抛出 `PcaToolDenied` 而工具不运行。 护栏和 `needsApproval` 帮助者覆盖跑道关口和人或监护人的升级.

包被鸭子打到SDK上:它没有运行时间依赖 `@openai/agents` 并使用任何兼容的版本.

## 安装

```sh
npm i @atlasauth/pca-openai-agents
```

取决于 `@atlasauth/pca` 财务报告和审定财务报表 `@atlasauth/pca-ai-sdk`。 。 。 .

## 使用量

```ts
import { tool, Agent, run } from '@openai/agents';
import { withPcaTool, pcaInputGuardrail } from '@atlasauth/pca-openai-agents';

const refund = tool({ name: 'refund', description: '...', parameters, execute: doRefund });

const guarded = withPcaTool(refund, {
  verify: { grant },              // pcaAgent.grant: the signed Root Intent Grant the proof must chain to
  audience: 'ins_my_server',      // must equal the PCActn's signed aud (null = accept any)
  verb: 'stripe.refund',          // bind the proof to this tool
});

const agent = new Agent({
  name: 'support',
  tools: [guarded],
  inputGuardrails: [pcaInputGuardrail({ verify: { grant }, audience: 'ins_my_server' })],
});

// The agent holding the grant produces the proof (see @atlasauth/pca); it rides on the run context.
const { encoded } = pcaAgent.act('stripe.refund', 'charge:ch_1', toolInput, { aud: 'ins_my_server' });
await run(agent, input, { context: { pca: encoded } });
```

默认情况下,该证明从 `context.pca` (或 `context.pcaProof`; 通过 `require` 从工具输入或其他地方读取. `verify` 也可以是一个函数 `(pcactn) => VerifyResult`。 。 。 .

## API 密码

-   `withPcaTool(tool, options)` 编号 : `pcaTools(record, options)` - 包裹一个工具/一组
-   `pcaInputGuardrail(options)`, (中文(简体) ), `pcaToolGuard(options)` - SDK警卫员,在没有有效证据的情况下
-   `pcaNeedsApproval(options)`, (中文(简体) ), `withApproval(tool, options)` - 将危险工具映射到SDK的 `needsApproval` 使用五氯苯甲醚分级
-   `reviewToolCall(...)`, (中文(简体) ), `pendingStepUps(reviews)` - 输入一个批准信箱
-   `PcaToolDenied` (与 `kind`数字 : `missing | malformed | verify | binding`, (中文(简体) ), `proofFromRunContext`, (中文(简体) ), `proofFromInputHeaders`

## 状态

部分 [证明机构](https://github.com/Atlas-Authorization/pca). 核查是真实的(签名、能力链、计划包容、受众、有效性窗口、计数器),但只有您配置的赠款和大门才强大。 它保护当地代理-执行边界;当一个工具呼叫远程服务时,该服务本身的核查员仍然是权威. PCA的密码学没有经过独立审计.

## 许可证

麻省理工学院 - 见LICENSE

## 常见问题

### @atlasauth/pca-openai-agents 是什么？

OpenAI Agents SDK \(@openai/ agents\) PCA的守护者: guardrail \+ 工具-执行钩,所以每个代理工具呼叫都是由证明-携带\+政策-加分\.

### 如何安装 @atlasauth/pca-openai-agents？

在项目目录运行 npm install @atlasauth/pca-openai-agents，或使用 pnpm add / yarn add / bun add。

### @atlasauth/pca-openai-agents 支持 TypeScript 吗？

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

### @atlasauth/pca-openai-agents 支持 ESM 还是 CommonJS？

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

### @atlasauth/pca-openai-agents 需要什么版本的 Node\.js？

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

### @atlasauth/pca-openai-agents 可以商用吗？

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

### @atlasauth/pca-openai-agents 的下载量有多少？

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

### @atlasauth/pca-openai-agents 还在维护吗？

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