# @agenticprimitives/service-agent 中文文档

规范地址：https://npmcn.com/package/%40agenticprimitives/service-agent/

版本：0\.0\.0-alpha\.33
npm 元数据更新时间：2026-10-26T11:49:31.998Z
中文译文更新时间：2026-11-06T07:32:31.610Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：88 kB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-01T10:43:55.736Z
- 最新版本发布：2026-10-26T11:49:30.812Z
- 近 30 天下载量：4127（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

通用服务代理能力框架(第283项):定义 - > 断言 - > 授权 - > 代表 - > 原始计划 - > 执行 - > 收到。 提供者中性;所有权威评审员+原始人被注射. 域目录( 如 @ agenticprimitives/ treasury)

## 安装

```sh
npm install @agenticprimitives/service-agent
```

也可以使用：`pnpm add @agenticprimitives/service-agent`、`yarn add @agenticprimitives/service-agent`、`bun add @agenticprimitives/service-agent`

## README

# @ agenticprimitives/ service-agent( 服务代理)

> 部分 **[代理先导](https://agenticprimitives.dev/)** ——代理应用程序的开源信任底板:可以签名的身份,行为时间检查权限,所有者携带的证据. [开发者工具包](https://github.com/agentictrustlabs/agentic-primitives) • 妇女 [所有软件包](https://agenticprimitives.dev/developers)

> **状态 :** 实验(Spec 283 PR1).

建筑通用框架 **服务代理商** - 暴露能力目录的特工 (技能),并在分层的权力下执行。 它不偏重任何供货商,而纯于环0:仅取决于 打开 `@agenticprimitives/types` 并且不进口钱包、交换、RPC、MCP、授权或政策代码。 这个 具体提供者和主管部门评价员 **已注射** 以主妇盟誓.

域目录——如. `@agenticprimitives/treasury` ——是分别提供技能定义的包

-   供货商中立的计划; 此套件运行生命周期.

## 生命周期

```
define  →  assert  →  entitle / delegate  →  primitive-plan  →  execute  →  receipt
```

-   **定义** a 包括: `SkillDefinition` 说明一种技能的含义: id, version, `effect` (单位:千美元)`read|sign|spend|trade|admin`),默认 `exposure`逻辑能力 `requires`选项 我/O计划,和a `compile()` 发出一个 **原始计划**定义并不声称主机可以 运行它.
-   **主张** —— 说 `assertSkills` 解决每个定义的 `requires` 反对: `PrimitiveRegistry`A级 技能要求只当每个非可选要求与安装的 `Primitive` 谁 约束 **覆盖** 要求(模拟)。 结果是 `AssertionReport` (单位:千美元)`asserted` 编号 : `unavailable` 编号 : `rejected`) (中文(简体) ). 可选 `publishAssertion` 钩子是公用的接缝 (第282项:金库索赔) `atl:skills` —发现+A2A卡.
-   **授权/代表/警卫** - 计划 `.authorize('entitlement', …)`, (中文(简体) ), `.authorize('delegation', …)` 财务报告和审定财务报表 `.guard(…)` 步骤 **已注射** 评估员(制图员) `tool-policy`编号 :`entitlements`, (中文(简体) ), `delegation`,以及 `tool-policy` (掌声) 每道门必须ALLOW;第一次拒绝投出键入 错误和无进一步运行( 未关闭) .
-   **原始计划/ 执行** —— 说 `runPlan` 决定 `ref()`s, 呼叫注册原始人 `.step`编号 (加内置) `ledger.reserve`编号 :`ledger.finalize`),并收取 `.output`。 。 。 .
-   **收据** —— 说 `invoke` 返回已规范 `ExecutionReceipt` (权威决定+原始约束)
    -   输出);主汇/通过 `audit`。 。 。 .

## 示例

```ts
import { ServiceAgent, defineSkill, createPrimitiveRegistry, primitivePlan, ref } from '@agenticprimitives/service-agent';

const balance = defineSkill<{ accountId: string }, { balance: string }>({
  id: 'treasury.account.balance', version: '1.0.0', name: 'Read balance',
  effect: 'read', defaultExposure: 'authenticated',
  requires: [{ capability: 'account.balance' }],
  compile: ({ input }) =>
    primitivePlan('plan.balance')
      .step('bal', 'account.balance', { accountId: input.accountId })
      .output({ balance: ref('bal', 'balance') }),
});

const registry = createPrimitiveRegistry();
registry.register(myAccountProvider); // advertises { id: 'account.balance', version, constraints }

const agent = new ServiceAgent({ descriptor: { id: '0x…', name: 'Treasury', version: '1.0.0' }, primitives: registry });
agent.define(balance);
await agent.assert();
const receipt = await agent.invoke({ skillId: 'treasury.account.balance', input: { accountId: 'acct-1' } });
```

花的技巧,加点 `.authorize('entitlement', …)`, (中文(简体) ), `.authorize('delegation', …)`, (中文(简体) ), `.guard(…)`,则 分类账储备/最后敲定步骤;电线 `entitlements` 编号 : `delegations` 编号 : `policies` 编号 : `ledger` 输入 `ServiceAgentOptions`。见 `test/conformance.test.ts` 整个生命周期都有假货.

## 住在别的地方

-   **供应商** (EVM转让、互换地点、RPC、KMS签名)——EXTERNAL(ADR-0037);它们登记为 `Primitive`s. 德摩斯船伪造.
-   **权威逻辑** —— 说 `delegation`, (中文(简体) ), `tool-policy`, (中文(简体) ), `entitlements`;作为评价员注入.
-   **国库目录** —— 说 `@agenticprimitives/treasury`。 。 。 . **公开披露** - 应用程序,通过 `publishAssertion` (第282页).

## 常见问题

### @agenticprimitives/service-agent 是什么？

通用服务代理能力框架\(第283项\):定义 - \> 断言 - \> 授权 - \> 代表 - \> 原始计划 - \> 执行 - \> 收到。 提供者中性;所有权威评审员\+原始人被注射\. 域目录\( 如 @ agenticprimitives/ treasury\)

### 如何安装 @agenticprimitives/service-agent？

在项目目录运行 npm install @agenticprimitives/service-agent，或使用 pnpm add / yarn add / bun add。

### @agenticprimitives/service-agent 支持 TypeScript 吗？

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

### @agenticprimitives/service-agent 支持 ESM 还是 CommonJS？

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

### @agenticprimitives/service-agent 可以商用吗？

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

### @agenticprimitives/service-agent 的下载量有多少？

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

### @agenticprimitives/service-agent 还在维护吗？

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