# @agentpos/core 中文文档

规范地址：https://npmcn.com/package/%40agentpos/core/

版本：0\.1\.5
npm 元数据更新时间：2026-10-29T15:43:53.944Z
中文译文更新时间：2026-11-08T01:35:58.653Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40agentpos/core
原文对照：https://npmcn.com/package/%40agentpos/core/?lang=original
项目主页：https://agentposhq.com/
源码仓库：https://github.com/NovaCorpAI/agentpos

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

- 包体积（解压后）：849 kB，220 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.5
- 运行依赖：8 个
- 首次发布：2026-10-26T21:02:05.517Z
- 最新版本发布：2026-10-29T15:43:52.885Z
- 近 30 天下载量：1934（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

AgentPOS核心:配置,货币类型,协议适配器(x402,UCP,ACP),签名厂,LLM路由器,财政接口.

## 安装

```sh
npm install @agentpos/core
```

也可以使用：`pnpm add @agentpos/core`、`yarn add @agentpos/core`、`bun add @agentpos/core`

## README

# @ agentpos/ core (% 1) (帮助)

每一个 AgentPOS 软件包的共同基础 .

-   `config`: Network(testnet默认,主网出闸口),主持人URL,CAIP-2代号,USDC发行商.
-   `money`:品牌整数类型(`UsdcMinor`, (中文(简体) ), `Stroops`),7个小数,没有浮点. `rescaleMinor` 在小单位之间精确地移动一个数量,并拒绝圆形.
-   `chain`: 网络作为数据。 CAIP-2 标识,a `ChainProfile` 每个网络(美联储十进制) 网络,地址检查,探索者链接)和注册铁路包添加到. 斯特拉尔船 内建; `usdcOnChain(price, caip2)` 表示该网络的USDC单元中的目录价格.
-   `wallet-proof`: 证明商人通过签署非ce控制接收钱包 (护栏一. Stellar使用SEP-53;其他家庭登记其核查人.
-   `errors`数字 : `AgentPOSError { code, message, hint, retryable }` 带有闭合代码集.
-   `adapter/x402`: 唯一导入模块 `@x402/*`。资源服务器,路由配置 整数价格、买方客户端、结算 -- > 收款.
-   `adapter/rails`页:1 `PaymentRail` 接口及其登记册(见下文“支付栏”).
-   `adapter/ucp`, (中文(简体) ), `adapter/acp`: 发现表面 (skeletons; 第2阶段的 schema验证).
-   `adapter/versions`: 绑定协议版本和 `adapterVersion`。 。 。 .
-   `signer`: 工厂 `local-keypair` (钱包基特和密码是预留的插槽).
-   `llm`:直接-HTTP路由器(Anthropic Messages API,OpenAI-兼容).
-   `fiscal`数字 : `FiscalAdapter` 接口(插件在别处).

```ts
import { resolveConfig, usdc, createResourceServer, buildRouteConfig } from "@agentpos/core";

const cfg = resolveConfig(); // testnet
const server = createResourceServer(cfg);
const route = buildRouteConfig(cfg, { payTo: "G...", amount: usdc("1.25"), reference: "order_1" });
```

## 从 npm 安装: Zod 覆盖

`@x402/core` (x402 SDK 此包包包) 声明 `zod@^3`,3.x线没有补丁 页:1 [全球统一制度A-mrhx-c7xc-m3w5](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5)这样 `npm audit` 在任何安装的工程中报告 `@agentpos/core`。SDK只使用 Zod API 即 与 zod 4 相同, 此寄存器运行整个测试套件和测试网支付回路 与 zod 4 齐发. 在 SDK 移动之前, 将此添加到您的项目中 `package.json`数字 :

```json
{ "overrides": { "zod": "^4.6.6" } }
```

随着pnpm,同样的下去 `pnpm.overrides` (或 `overrides` 内 `pnpm-workspace.yaml`) (中文(简体) ).

## 支付栏杆

A 类 **铁路** 一种方式是支付商店。 有两个: x402 / USDC 超过 Stellar (单位:千美元)`org.x402.stellar`,在分类账上结算)和 Transbank Webpay / 点击智利的卡片 (单位:千美元)`cl.transbank.webpay`,在商人自己的收购人处结算. 这个 `PaymentRail` 接口是 是什么使得第二个是添加而不是重写, 以及下一个是什么(网络代理 证书)也将执行.

```ts
import { createTransbankRail, fiatMinor, minorAmount } from "@agentpos/core";

// The merchant's own commerce code and API key: never ours (guardrail 7).
const card = createTransbankRail({
  environment: "integration",
  commerceCode: process.env.TRANSBANK_COMMERCE_CODE!,
  apiKey: process.env.TRANSBANK_API_KEY!,
  oneclick: { mallCode: "597055555541", childCommerceCode: "597055555542" },
});
const clp = minorAmount(fiatMinor("14990", 0, "CLP"), "CLP", 0); // whole pesos, no floats

// Webpay Plus: a first purchase. The human pays on Transbank's page; verify reports
// PAYMENT_PENDING until then; settle commits the token exactly once.
const first = await card.quote({ payTo: returnUrl, amount: clp, reference: "cart_1" });
// Oneclick: a repeat purchase on a card the buyer enrolled once. No human step.
const again = card.quoteOneclick({ payTo: "store", amount: clp, reference: "cart_2" });
await card.settle({ mode: "oneclick", username: "buyer-42", tbkUser: "tbk_..." }, again.terms);
```

卡片结算不产生散列交易: `reference` 是商店的购买订单,和 获取者的授权代码 `raw`。 。 。 . `fiatMinor(decimal, decimals, currency)` 转出 源价格为整数小数(CLP0小数,2美元); `fiatDecimals(code)` 已经知道 释相.

```ts
import { createX402StellarRail, PaymentRailRegistry, usdcAmount, usdc } from "@agentpos/core";

const rails = new PaymentRailRegistry([createX402StellarRail({ config: cfg })]);
const rail = rails.requireSupporting({ currency: "USDC", amount: usdcAmount(usdc("1.25")) });

const quote = await rail.quote({
  payTo: "G...",
  amount: usdcAmount(usdc("1.25")),
  reference: "cart_1",
});
const decision = await rail.verify(paymentPayload, quote.terms); // never moves money
const settlement = await rail.settle(paymentPayload, quote.terms); // { settled, reference: txHash }
```

5种方法: `supports(ctx)` (网络、货币和金额界限;纯), `quote(input)` (术语) a. 代理人必须满足,对于x402是逐一满足402个付款要求, `verify`, (中文(简体) ), `settle` 财务报告和审定财务报表 `describe()` 用于发现表面.

每条铁路有三项规则:

-   **添加一道栏从不改变商店的目录或订单表面.** 物品、推车、引文和 订购单与使用的铁路相同;铁路只增加一名付款管理人 发现和在 `rail` 栏.
-   **钱总是一个小单位的整数** (护栏4): `UsdcMinor`,或一个 `MinorAmount` (单位:千美元)`{ minor: bigint, currency, decimals }`用另一种货币定价的铁路。 没有浮点 在接口的任何地方.
-   **失败者说它是哪一种.** `RailFailure.kind` 实值 `"rejected"` (铁轨说没有); 确定性,绝不重试)或 `"unavailable"` 铁路没有应答,只有一条铁路是可试的 (b) 发生故障时可采取行动)。 为了解决问题, `preSubmission: true` 额外意味着请求 6号护卫车厢禁止重新投放其他东西 代码来自 基础适配器不变(`PAYMENT_REJECTED`, (中文(简体) ), `SETTLEMENT_FAILED`, (中文(简体) ), `FACILITATOR_UNAVAILABLE`); 铁道包装器从不给故障重新贴上标签.

`PaymentRailRegistry` 命令和id-index: `list()`, (中文(简体) ), `get`编号 :`require`, (中文(简体) ), `firstSupporting(ctx)`, (中文(简体) ), `describe()`它坚守 **无路线政策** - 阈值、优惠和代理规则是 商人的和属于 `packages/policy`. 铁路标识是固定在 `adapter/versions.ts` (单位:千美元)`PAYMENT_RAIL_IDS`, (中文(简体) ), `RESERVED_PAYMENT_RAIL_IDS`) (中文(简体) ).

脚本 : `pnpm e2e:smoke` (testnet friendbot + trustline + 支付,打印tx hashes).

## 网络和钱包链接

核心是中性的,关于一个商店的哪个连锁付款。 网络是 `ChainProfile`数字 :

```ts
import { registerChainProfile, FAMILY_ADDRESS_CHECKS, usdcOnChain, usdc } from "@agentpos/core";

// A rail package registers its network once, at import.
registerChainProfile({
  caip2: "eip155:5042002",
  family: "eip155",
  label: "Arc testnet",
  testnet: true,
  usdcDecimals: 6,
  isValidAddress: FAMILY_ADDRESS_CHECKS.eip155,
});

usdcOnChain(usdc("1.5"), "stellar:pubnet"); // { minor: 15000000n, decimals: 7 }
usdcOnChain(usdc("1.5"), "eip155:5042002"); // { minor: 1500000n, decimals: 6 }
usdcOnChain(usdc("1.2345678"), "eip155:5042002"); // INVALID_AMOUNT: never rounded
```

连接一个商人钱包从不碰钥匙:商店发出挑战,商号 在他们自己的钱包, 商店验证它.

```ts
const challenge = createWalletChallenge({
  caip2: "stellar:pubnet",
  address: "G...",
  domain: "shop.example.com",
});
// ...the merchant signs challenge.message in Freighter (SEP-53)...
await verifyWalletProof(challenge, signatureBase64); // throws WALLET_PROOF_INVALID / _EXPIRED
```

## 常见问题

### @agentpos/core 是什么？

AgentPOS核心:配置,货币类型,协议适配器\(x402,UCP,ACP\),签名厂,LLM路由器,财政接口\.

### 如何安装 @agentpos/core？

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

### @agentpos/core 支持 TypeScript 吗？

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

### @agentpos/core 支持 ESM 还是 CommonJS？

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

### @agentpos/core 需要什么版本的 Node\.js？

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

### @agentpos/core 可以商用吗？

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

### @agentpos/core 的下载量有多少？

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

### @agentpos/core 还在维护吗？

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