# @braintrust/pi-extension 中文文档

规范地址：https://npmcn.com/package/%40braintrust/pi-extension/

版本：2\.2\.2
npm 元数据更新时间：2026-10-28T18:02:04.417Z
中文译文更新时间：2026-11-08T13:48:53.362Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40braintrust/pi-extension
原文对照：https://npmcn.com/package/%40braintrust/pi-extension/?lang=original
源码仓库：https://github.com/braintrustdata/braintrust-coding-agent-plugins

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

- 包体积（解压后）：84.6 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@earendil-works/pi-coding-agent \*
- 首次发布：2026-04-08T15:49:52.392Z
- 最新版本发布：2026-10-28T18:02:03.301Z
- 近 30 天下载量：33836（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

派的大脑信任扩展. 包括Pi会话的自动追踪、转弯、LLM呼叫和Braintrust的工具处决.

## 安装

```sh
npm install @braintrust/pi-extension
```

也可以使用：`pnpm add @braintrust/pi-extension`、`yarn add @braintrust/pi-extension`、`bun add @braintrust/pi-extension`

## README

# @ raintrust/ pi- extension (英语)

[![npm version](https://img.shields.io/npm/v/%40braintrust%2Fpi-extension)](https://www.npmjs.com/package/@braintrust/pi-extension)

追踪 [Pi](https://github.com/earendil-works/pi-coding-agent) 届会 大脑信任。 扩展发送事件给本地 `bt` 守护进程, 它正在构建 并上传痕迹。 如果追踪失败, Pi 继续运行 .

## 追踪的是什么

-   **会期**: 每个 Pi 会话有一个根跨, 至少一个转弯
-   **转弯跨度**: 每个用户提示/代理运行一个跨度
-   **LLM 跨度**:在一转内每个模型响应一个跨度,其中包含符号用法,缓存用法,推理符号,估计费用,到第一符号的时间,以及该请求可用的工具定义. 通过虚拟模型,跨度将物理模型和思维级别命名为: `selected_model`
-   **工具间距**:每个工具执行一个跨度,包括动态加载的工具. 工具调用另一个工具, 如代码脚本 `tools.<name>()` 呼叫,在呼叫工具的跨度下嵌入
-   **压缩跨度**:每会话压缩一个间隔,包括可用时触发/重试元数据
-   **部门摘要**: 每个摘要一个跨度 `/tree` 导航分支

追踪形状 :

```text
Session (task)
├── Turn 1 (task)
│   ├── anthropic/claude-sonnet-4 (llm)
│   │   ├── read: package.json (tool)
│   │   └── bash: pnpm test (tool)
│   └── anthropic/claude-sonnet-4 (llm)
├── Compaction (task)
├── Branch Summary (task)
└── Turn 2 (task)
```

## 快速启动

安装 Pi 和 [大脑信任CLI](https://www.braintrust.dev/docs/reference/cli/quickstart),然后运行 :

```bash
bt login
bt trace enable pi --project my-coding-agent
pi
```

安装扩展并保存其配置。 使用 `--profile` 或者说 `--org` 选择一个简介或组织。 如果已打开, 则重新启动 Pi . 脚印显示追踪状态,并在可用时显示追踪的链接.

要单独安装 npm 扩展, 请使用 `pi install npm:@braintrust/pi-extension`,然后以 `bt trace enable pi`。 。 。 .

在不改变全球追踪配置的情况下

```bash
bt trace run --project my-coding-agent pi -- -p "summarize this repository"
```

这个 `bt trace run` 路由和元数据旗也接受它们的匹配 `BRAINTRUST_*` 环境变量; 平原 `pi` 会话扩展名没有 . Pi 不支持历史导入和活附着。 升级活动 来自守护进程前扩展的会话被支持: 当其本地遗留状态 文件仍然存在,守护进程延续了现有的Braintust根并 转动顺序。 如果该状态被移除或无效,则安全启动跟踪 替换新守护进程.

## 兼容性

CI 运行一个可追踪的 Pi 会话, 并使用最近补丁的包装扩展 从最后5个稳定的 Pi 释放线的每一个。 兼容工作 在每个运行中解决这些版本,包括 Pi 前 npm 的发布 需要时的软件包名称.

软件包检测偏好运行中的 CLI 而不是扩展本地对等依赖 . Pi相容主机被一个 `piConfig` 字段或已知的软件包名称, 包括Oh My Pi (英语:`@oh-my-pi/pi-coding-agent`) (中文(简体) ). 追踪记录主机 软件包名称 `metadata.host_name` 及其版本在 `metadata.pi_version`。 。 。 .

## 配置

按此顺序设置加载, 后面的值优先 :

1.  默认
2.  `~/.pi/agent/braintrust.json`
3.  `.pi/braintrust.json` 在项目中(或 Pi 配置的项目配置目录)
4.  `bt trace run` 引用的设置

示例

```json
{
  "trace_to_braintrust": true,
  "route": {
    "auth": { "profile": "work", "org_name": "acme" },
    "destination": { "type": "project_logs", "project_name": "pi" },
    "additional_metadata": { "team": "platform" }
  }
}
```

### 设置

| 配置密钥 | 默认 | 目的 |
| --- | --- | --- |
| `trace_to_braintrust` | `false` | 启用跟踪 |
| `route.auth.profile_id` | 未设定 | 保存的配置文件 ID `bt` 设置 |
| `route.auth.profile` | 默认 `bt` 配置文件 | 按名称选择配置文件 |
| `route.auth.org_name` | 配置默认 | 选择一个组织 |
| `route.destination` | 项目日志 `pi` | 选择跟踪目的地 |
| `route.additional_metadata` | 未设定 | 添加 root- span 元数据 |
| `route.flush_mode` | `flush_on_turn_end` 默认路径 | 控制交货冲洗 |
| `show_ui` | `true` | 显示状态指示; 覆盖到 `BRAINTRUST_SHOW_UI` |
| `show_trace_link` | `true` | 显示跟踪链接; 覆盖到 `BRAINTRUST_SHOW_TRACE_LINK` |

旧文件仍然可以使用顶级 `profile`, (中文(简体) ), `org_name`, (中文(简体) ), `project`,以及 `additional_metadata`。对于新文件,使用 `bt trace enable` 或被窝 `route` 上方的格式。 提供路由时包含目的地 .

只有显示设置直接读取环境变量 。 追踪设置 来自这些文件或 `bt trace run`全权证书由 `bt`。 。 。 .

提供者请求的元数据仅限于模型、思维、产出限制和 工具计数设置。 完全提供者的有效载荷和思维签名被省略.

## 管理追踪

```bash
bt trace doctor pi
bt trace status
bt trace update pi
bt trace disable pi
```

## 地方发展

从 monrepo 根中,在加载后先建立扩展 :

```bash
make build-pi
pi -e ./dist/pi/dist/index.mjs
```

这将加载一个运行的扩展; 它仍然需要一个启用的 Brain Trust 配置 。 运行 `make validate-pi` 用于包检查。 见 [捐款指南](https://github.com/braintrustdata/braintrust-coding-agent-plugins/blob/main/src/plugins/pi/content/CONTRIBUTING.md) 用于源开发指令.

## 常见问题

### @braintrust/pi-extension 是什么？

派的大脑信任扩展\. 包括Pi会话的自动追踪、转弯、LLM呼叫和Braintrust的工具处决\.

### 如何安装 @braintrust/pi-extension？

在项目目录运行 npm install @braintrust/pi-extension，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@earendil-works/pi-coding-agent（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @braintrust/pi-extension 支持 TypeScript 吗？

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

### @braintrust/pi-extension 支持 ESM 还是 CommonJS？

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

### @braintrust/pi-extension 可以商用吗？

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

### @braintrust/pi-extension 的下载量有多少？

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

### @braintrust/pi-extension 还在维护吗？

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