# @datalayer/personal-agent-protocol 中文文档

规范地址：https://npmcn.com/package/%40datalayer/personal-agent-protocol/

版本：0\.32\.0
npm 元数据更新时间：2026-11-07T19:23:45.130Z
中文译文更新时间：2026-11-11T14:51:06.176Z
软件包许可：BSD-3-Clause

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

原始 npm 页面：https://www.npmjs.com/package/%40datalayer/personal-agent-protocol
原文对照：https://npmcn.com/package/%40datalayer/personal-agent-protocol/?lang=original
项目主页：https://github.com/datalayer/personal-agent-protocol#readme
源码仓库：https://github.com/datalayer/personal-agent-protocol

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

- 包体积（解压后）：4.2 MB，197 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-10-10T09:01:29.417Z
- 最新版本发布：2026-11-07T19:23:44.766Z
- 近 30 天下载量：12859（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

个人代理协议 0.4 (2026-11-06) 及其操作扩展 v2

## 安装

```sh
npm install @datalayer/personal-agent-protocol
```

也可以使用：`pnpm add @datalayer/personal-agent-protocol`、`yarn add @datalayer/personal-agent-protocol`、`bun add @datalayer/personal-agent-protocol`

## README

[![Datalayer](https://images.datalayer.io/legacy/datalayer-25.svg)](https://datalayer.ai/)

# 个人代理协议

Python 和 SDK 类型 [个人代理协议](https://personalagentprotocol.org/): 两者都执行 [版本 0.4](https://personalagentprotocol.org/docs/spec) (2026-11-06) (中文(简体) ) 草稿 `46beb21`,及其操作扩展v2. 见 [兼容性](https://personal-agent-protocol.datalayer.tech/releases/compatibility/), (中文(简体) ), [移徙](https://personal-agent-protocol.datalayer.tech/releases/migration/), (中文(简体) ), 页:1 [遵守情况报告](https://personal-agent-protocol.datalayer.tech/protocol/conformance-report/), (中文(简体) ), 财务报告和审定财务报表 [支助](https://personal-agent-protocol.datalayer.tech/releases/support/)。 。 。 .

![Personal Agent Protocol demo](https://images.datalayer.io/products/personal-agent-protocol/pap-demo.gif)

PAP让个人代理发现并代表公司代理交谈 一个人 该公司仍对其身份、授权、, 个人代理人不需要个人公司 密码或他们的账户数据副本.

## 一分钟后了解 PAP

典型的相互作用有五个部分:

1.  **发现** ——个人代理阅读公司公众信息 `/.well-known/poppy.json` 文档.
2.  **开始会话** - 个人代理人的名字,新会话本身,签名 退出,并为每个请求签署一个会话.
3.  **旋转** - 个人代理人可以提问而不透露 个人的公司身份.
4.  **需要时签名** ——公司自开授权页. 证书在个人和公司之间.
5.  **继续安全** - 同样的谈话恢复 带有访问符 除了签名的会话标题之外.

```mermaid
sequenceDiagram
    actor Person
    participant PA as Personal agent
    participant Company as Company agent
    participant Auth as Company authorization server

    PA->>Company: Discover /.well-known/poppy.json
    Company-->>PA: Agent, API, and authorization endpoints
    PA->>PA: Start a signed-out Session, no request sent
    PA->>Company: Start a conversation, with a signed Session header
    Company-->>PA: Sign-in required for account data
    PA-->>Person: Open the company's sign-in page
    Person->>Auth: Sign in and approve scopes
    Auth-->>PA: Refresh token and access token
    PA->>Company: Continue the same conversation, with the access token
    Company-->>PA: Account-aware response
```

SDKs执行这些协议和安全机械. 他们不决定 代理人应该说什么,它应该使用哪种模式,或者是否提议 行动适合一个人.

## 安装和发现公司

### 蟒

```bash
python -m pip install personal-agent-protocol
```

```python
import asyncio

from personal_agent_protocol import DiscoveryClient


async def main() -> None:
    async with DiscoveryClient() as client:
        company = await client.discover("example.com")
        print(company.document.organization.name)
        print(company.document.agent.protocols)


asyncio.run(main())
```

### 类型脚本

```bash
npm install @datalayer/personal-agent-protocol
```

```typescript
import { discoverCompany } from '@datalayer/personal-agent-protocol';

const company = await discoverCompany('example.com');
console.log(company.document.organization.name);
console.log(company.document.agent.protocols);
```

发现是故意的 一个小的第一个例子。 生产会议, 签入,对话流量也需要主机拥有的签名密钥,授权 键控、 令牌存储和浏览器交接 。 这些能力是: 通过反应堆而不是隐藏的全球状态提供.

## 反应堆是扩展基础

两个SDK都是建立在 [数据层反应堆](https://github.com/datalayer/reactor),输入插件和 缴款制度。 应用程序从明确的 PAP 主机组装 用于:

-   发现运输和URL安全政策;
-   协议简介和扩展处理器;
-   时钟和密码随机性;
-   签署、授权钥匙和会话JWT;
-   双向身份、信使存储和缓存;
-   浏览器移交和授权状态存储;
-   PAP或第三方扩展提供的CLI命令.

此架构在允许桌面的同时保留协议核心可移植性 应用程序、浏览器应用程序、服务器或测试用带以提供 安全和平台行为适合其环境。 失踪或 含糊不清的安全捐款没有结清.

Python 接受主机组装反应堆 `PluginPlatform`数字 :

```python
from reactor import PluginManifest

from personal_agent_protocol import DiscoveryClient, build_pap_reactor


async def discover_with_host() -> None:
    platform, owned_http = build_pap_reactor(
        plugins=[
            (PluginManifest(name="my-security", version="1"), my_security_plugin)
        ]
    )
    try:
        async with DiscoveryClient(reactor=platform) as client:
            company = await client.discover("example.com")
            print(company.document.organization.name)
    finally:
        platform.stop()
        if owned_http is not None:
            await owned_http.aclose()
```

TypeScript 可构建主机或接收已存在的 `ReactorPlatformView`数字 :

```typescript
import {
  buildPapReactor,
  discoverCompany,
} from '@datalayer/personal-agent-protocol';

const reactor = buildPapReactor({}, [mySecurityPlugin]);
const company = await discoverCompany('example.com', { reactor });
```

见 [反应堆存放处](https://github.com/datalayer/reactor) 联 合 国 插件模型和贡献生命周期.

## B. 已执行的内容

Python 和 TypeScript 共享定着并覆盖同一主协议 表面 :

| 区域 | 当前支助 |
| --- | --- |
| 模型 | 与前向兼容的发现, OAuth 元数据, 客户端元数据, 消息, 事件, 以及 Operation v2 模型 |
| 发现 | `poppy.json`,公司域和发行方验证,限定响应,并重定向控制 |
| 会议 | 对等用户ID, 本地会话由随机命名 `sid`,每个请求的会话 JWT, 并编辑符号 |
| 密码学 | ES256/PS384 JOSE、委托钥匙和代表团、会议JWT的创建和核查、盲目签字和重放检查 |
| 直接签名 - 单位 | State, S256 PKCE, 回调验证, 浏览器交接, 以及单用代码交换管弦 |
| 浏览器会话 | 一次性代码,代理以会话标题授权它,控制格式 POST,以及重放安全性验证 |
| 运输 | 主机拥有的授权和会话标题,每次尝试一次新鲜的会话 JWT,一次在之后重启 `invalid_session`,没有方向 |
| 对话 | 开始和继续,随机用户-全球消息ID,命令长投票,光标恢复,重复压制,安全出错 |
| 扩展性 | 用于平台、安全、协议、储存和CLI行为的反应堆贡献点 |
| 国 际 | 非机密简介、公司核查、扩展诊断和版本的JSON输出 |

Python 额外提供了 SQLite 双向识别的参考提供者. 便携式 TypeScript 条目拒绝明显的本地和私有文字 地址 电话地址 其明确的服务器条目添加 `NodeUrlSafetyPolicy` 财务报告和审定财务报表 `createResolvingFetch` (A/AAAA决议,每个地址都是全球的,经过审查的。) 拨号, `JoseSigner`,并检查公司制作的会话标题:

```typescript
import {
  JoseSigner,
  NodeUrlSafetyPolicy,
} from '@datalayer/personal-agent-protocol/server';
```

重复JSON成员在Python和TypeScript信任边界被拒绝.

## 尚未执行的

在SDKs和SDKs中,执行0.4草案和操作v2的每一流程 两个参考公司:发现、会话、直接、装置和介质 签入、刷新令牌、DPoP、OpenAPI和MCP、与SSE的对话、交接和 关闭、浏览器会话、反馈和操作。 剩下的是:

-   生产后端 主机贡献:没有 KMS/HSM 标志的 SDK 船 或长期委托保管的钥匙,没有耐用物品储存,只有内存 公司商店和回放缓存(`check_store` (一) 检查耐用;
-   帮助指南建议,但东道主今天决定:在 登录方法,将任务范围与持有的刷新符号相匹配,以及 在更广泛的登录后撤销以前的刷新令牌;
-   费率限额和 `RateLimit` 参考公司(主机可以)中的标题 贡献 `pap.company.rateLimit`),并用于日志和 痕迹;
-   在节点中,用于元数据获取的套接字 与此同时,DNS-约束间隔).

每项开放性或部分性要求及其理由列于 [议定书覆盖面](https://personal-agent-protocol.datalayer.tech/protocol/coverage/)。 。 。 .

## 安全边界

PAP证书属于主机,而不是代理模式或工具呼叫.

-   访问令牌、刷新令牌、会话JWT、授权代码和 双相标识符不得输入提示或可显示模型的工具结果.
-   Direct Sign-In需要主机提供的状态存储,浏览器交接,以及 签署捐款.
-   会话请求在合适之前关闭 `pap.signer` 财务报告和审定财务报表 `pap.sessionSigner` 已安装捐款.
-   拒绝从协议端点调试;调用 `Authorization`, (中文(简体) ), `DPoP`,以及 `Poppy-Session` 头被拒绝.
-   CLI 配置文件只存储配置 —— 绝不是符或私钥 .

指南对每一流动的这些界限加以解释,而不是将其作为: 适用公约.

## 命令行

Python 分布安装可扩展 `pap` 命令。 它的命令 使用反应堆的 `datalayer.reactor.cli` 进入点合同.

```bash
pap config set domain example.com --profile work
pap config show --profile work --json
pap company verify --profile work --json
pap extensions list --profile work
```

见 [CLI 指南](https://personal-agent-protocol.datalayer.tech/guides/cli/) 页:1 配置优先级、安全边界、机器可读输出以及 第三方扩展.

## 实例和第一消费者

这个 [`examples/pydantic-ai`](https://npmcn.com/package/%40datalayer/personal-agent-protocol/examples/pydantic-ai/) 目录包含小, 聚焦 Python 示例。 每个例子都教一个特征——发现,身份, 会话、 直接签名- In、 浏览器会话、 加密、 对话或 会话运输——不给模型提供协议秘密.

[数据层代理运行时间](https://github.com/datalayer/agent-runtimes) 这是 这些SDK的第一消费者。 它的个人代理协议画廊转动 与交互式反应堆/循环应用相同的特性,包括制导 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}人与公司之间的旅程 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}和运行时间的真实信息一起完成的 这个 美术馆的当地公司模拟器具有确定性,并明确识别; pAP客户,运输,验证, 和解析交换是真实的.

条目 `@datalayer/personal-agent-protocol/decks` 四艘飞船 [个案](https://personal-agent-protocol.datalayer.tech/examples/cases/) 作为甲板: `PAP_DECKS`, (中文(简体) ), `PAP_DECK_IDS` 财务报告和审定财务报表 `papDeck(id)`,每个带有 `yaml` 和同样的 甲板解析为 `spec`它带来了 `yaml` 和没有SDK.

每个已落实的特征应具有所有三个学习层面:

1.  此寄存器中的重点 SDK 示例;
2.  载有解释和人鱼序列图的Docusaurus指南;
3.  一个交互式代理运行时当一个用户界面实质性澄清 流动.

## 开发 SDKs

克隆寄存器,然后安装您的 SDK 的依赖性 改变.

### 蟒

```bash
python -m pip install -e '.[test,lint,typing,examples]'
python -m pytest personal_agent_protocol/__tests__
```

### 类型脚本

TypeScript包位于寄存器根. 源和检测在 `src/`; 已出版的 JavaScript 和声明发布到 `lib/`。 。 。 .

```bash
npm install
npm test
```

共有的固定装置在 `fixtures/`文档是 Docusaurus 的网址 `docs/`。 。 。 .

## 学多点

-   [文档](https://personalagentprotocol.org/docs)
-   [概览](https://personalagentprotocol.org/docs/introduction)
-   [规格](https://personalagentprotocol.org/docs/spec)
-   [执行指南](https://personalagentprotocol.org/docs/guides)
-   [扩展](https://personalagentprotocol.org/docs/extensions)
-   [开放话题](https://personalagentprotocol.org/docs/path-to-1#open-topics)
-   [数据层反应堆](https://github.com/datalayer/reactor)
-   [数据层代理运行时间](https://github.com/datalayer/agent-runtimes)

## 许可证

BSD 三相乐. 见 [`LICENSE`](https://npmcn.com/package/%40datalayer/personal-agent-protocol/LICENSE)。 。 。 .

## 常见问题

### @datalayer/personal-agent-protocol 是什么？

个人代理协议 0\.4 \(2026-11-06\) 及其操作扩展 v2

### 如何安装 @datalayer/personal-agent-protocol？

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

### @datalayer/personal-agent-protocol 支持 TypeScript 吗？

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

### @datalayer/personal-agent-protocol 支持 ESM 还是 CommonJS？

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

### @datalayer/personal-agent-protocol 可以商用吗？

@datalayer/personal-agent-protocol 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @datalayer/personal-agent-protocol 的下载量有多少？

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

### @datalayer/personal-agent-protocol 还在维护吗？

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