# @braintrust/trace-opencode 中文文档

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

版本：2\.1\.1
npm 元数据更新时间：2026-10-20T18:57:19.305Z
中文译文更新时间：2026-11-08T13:56:42.137Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：92.5 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@opencode-ai/sdk \>=1\.2\.25，@opencode-ai/plugin \>=1\.2\.25
- 首次发布：2026-02-09T17:32:55.173Z
- 最新版本发布：2026-10-20T18:57:18.871Z
- 近 30 天下载量：4034（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

自动追踪 OpenCode 对话到 Braintust. 获取用户消息,助理响应,工具要求可观察性.

## 安装

```sh
npm install @braintrust/trace-opencode
```

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

## README

# @ raintrust/ trace- opencode (中文(简体) )

追踪 [打开代码](https://opencode.ai/) 在Braintust的讲座。 插件发送 当地的活动 `bt` 守护进程, 它构建并上传痕迹 。 打开代码保存 如果追踪失败, 则运行 .

-   **会期**: 带有元数据( 工作空间、 主机名等) 的 OpenCode 会话根跨度
-   **转弯跨度**: 抓取每个用户辅助互动
-   **LLM 跨度**: 记录已完成的附有可用投入、产出和使用情况的示范信息
-   **工具间距**: 记录有投入和产出的单个工具处决

## 快速启动

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

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

此注册 npm 插件并保存其配置 。 使用 `--profile` 或者说 `--org` 选择一个简介或组织。 如果已打开, 则重新启动 OpenCode .

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

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

对 OpenCode 不支持历史导入和活附件 .

## 兼容性

软件包声明 `@opencode-ai/plugin` 财务报告和审定财务报表 `@opencode-ai/sdk` 同行人数 `>=1.2.25`. CI 检查包的安装在最低水平和 `latest`, (中文(简体) ), 并使用最新的 OpenCode CLI 运行真实代理集成测试.

## 配置

从这些文件中设置负载, 以工程设置压倒全局设置 :

-   全球: `$XDG_CONFIG_HOME/opencode/braintrust.json`,或 `~/.config/opencode/braintrust.json` 若为 `XDG_CONFIG_HOME` 未设置
-   项目: `.opencode/braintrust.json`

`bt trace run` 覆盖一次引用的跟踪设置。 合并文件 顶级:一个项目 `route` 替换全局 `route`。 。 。 .

```json
{
  "trace_to_braintrust": true,
  "enable_tools": true,
  "route": {
    "auth": { "profile": "work", "org_name": "acme" },
    "destination": { "type": "project_logs", "project_name": "my-project" }
  },
  "debug": true
}
```

### 设置

| 配置密钥 | 默认 | 目的 |
| --- | --- | --- |
| `trace_to_braintrust` | `false` | 启用跟踪 |
| `enable_tools` | `true` | 注册大脑信任工具; 覆盖到 `BRAINTRUST_OPENCODE_ENABLE_TOOLS` |
| `route.auth.profile_id` | 未设定 | 保存的配置文件 ID `bt` 设置 |
| `route.auth.profile` | 当前 `bt` 配置文件 | 按名称选择配置文件 |
| `route.auth.org_name` | 配置默认 | 选择一个组织 |
| `route.destination` | 项目日志 `opencode` | 选择跟踪目的地 |
| `route.additional_metadata` | 未设定 | 添加 root- span 元数据 |
| `route.flush_mode` | `fire_and_forget` 默认路径 | 控制交货冲洗 |
| `debug` | `false` | 启用调试日志; 覆盖方式 `BRAINTRUST_DEBUG` |

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

仅 `enable_tools` 财务报告和审定财务报表 `debug` 直接读取环境变量。 追踪 设置来自这些文件或 `bt trace run`。 。 。 .

## 禁用大脑信任工具

设定 `enable_tools` 改为 `false` 追踪OpenCode会话,而不注册Braintust品牌工具(`braintrust_query_logs`, (中文(简体) ), `braintrust_list_projects`, (中文(简体) ), `braintrust_log_data`, (中文(简体) ), `braintrust_get_experiments`:

```json
{
  "trace_to_braintrust": true,
  "enable_tools": false,
  "route": {
    "destination": { "type": "project_logs", "project_name": "my-project" }
  }
}
```

或使用环境变量:

```bash
BRAINTRUST_OPENCODE_ENABLE_TOOLS=false opencode
```

## 添加根元数据

设定 `route.additional_metadata` 将字段添加到根宽:

在不改变持久性配置的情况下引用一次,使用 `bt trace run --additional-metadata '{"ci": true, "run_id": "abc-123"}' opencode -- run "do the thing"`, (中文(简体) ), 或设置 `BRAINTRUST_ADDITIONAL_METADATA` 在该命令之前( 3)`bt trace run` 仍然接受它; 一个平地 `opencode` 会话插件没有).

您也可以通过配置文件设置 :

```json
{
  "route": {
    "destination": { "type": "project_logs", "project_name": "my-project" },
    "additional_metadata": { "team": "platform" }
  }
}
```

值必须是 JSON 对象 。 如果密钥冲突, 内建会话元数据将获胜 .

## 跟踪结构

守护进程重建会话、转弯、模式信息以及工具执行:

```text
Session (task)
├── Turn 1 (task)
│   ├── Model response (llm)
│   ├── Tool execution (tool)
│   └── Model response (llm)
└── Turn 2 (task)
```

当OpenCode提供时,模型使用和元数据也包括在内. 儿童 当关系是时,课程会附在父母的主动回合上 可供翻译者使用.

## 管理追踪

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

## 运行时架构

追踪向本地守护进程发送事件, 四个选择 大脑信任工具呼叫 `bt` 命令。 双用 `bt` 证书和API访问.

## 发展

从单列波根运行 `make validate-opencode` 用于构建、检查和测试 包裹。 见 [捐款指南](https://github.com/braintrustdata/braintrust-coding-agent-plugins/blob/main/src/plugins/opencode/content/CONTRIBUTING.md) 发展指示。 npm 软件包包含编译的切入点; 源变化属于单列波.

## 常见问题

### @braintrust/trace-opencode 是什么？

自动追踪 OpenCode 对话到 Braintust\. 获取用户消息,助理响应,工具要求可观察性\.

### 如何安装 @braintrust/trace-opencode？

在项目目录运行 npm install @braintrust/trace-opencode，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@opencode-ai/sdk（\>=1\.2\.25）、@opencode-ai/plugin（\>=1\.2\.25）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @braintrust/trace-opencode 支持 TypeScript 吗？

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

### @braintrust/trace-opencode 支持 ESM 还是 CommonJS？

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

### @braintrust/trace-opencode 可以商用吗？

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

### @braintrust/trace-opencode 的下载量有多少？

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

### @braintrust/trace-opencode 还在维护吗？

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