# @datadog/pi-plugin 中文文档

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

版本：0\.7\.22
npm 元数据更新时间：2026-10-26T17:53:13.240Z
中文译文更新时间：2026-11-11T13:31:31.187Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：327 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：3 个
- peer 依赖：typebox \*，@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-06-11T17:02:09.315Z
- 最新版本发布：2026-10-26T17:53:12.319Z
- 近 30 天下载量：44938（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

通过预配置 Datadog MCP 服务器在 Pi 编码代理中直接使用 Datadog. 查询日志,度量衡,痕迹,仪表板,以及更多的通过自然对话.

## 安装

```sh
npm install @datadog/pi-plugin
```

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

## README

# 数据犬 Pi 插件

查询数据犬 [Pi 编码代理](https://pi.dev/)询问日志、度量衡、痕迹、仪表板、显示器等等.

## 开始

安装插件、 重新启动 Pi并打开连接屏幕 :

```bash
pi install npm:@datadog/pi-plugin
```

```text
/datadog
```

选择您的 Datadog 网站并完成浏览器登录 。 Pi验证组织并保存连接. 没有配置名称或默认设置步骤:您的第一个连接会自动成为默认.

然后问一个数据犬问题:

```text
Show me error logs for the checkout service from the last hour.
```

证书在各项目之间重新使用,象征性地刷新。 普通查询从不启动浏览器登录. 如果授权到期或被撤销, 打开 `/datadog` 选择 **再说一遍**。 。 。 .

## 一个或多个组织

用一个保存的连接, `/datadog` 显示一个简单的连接菜单。 你不需要管理档案.

选择 **连接另一个组织** 添加另一个 org , 包括同一 Datadog 站点上的一个 。 保存了现有的证书和您的默认连接 。 一旦你有多个连接, `/datadog` 显示可搜索的组织拾取器 :

-   按组织、标签或域进行搜索的类型.
-   使用箭头键并 Enter 来切换此会话的连接 .
-   按 Tab 查找连接详情: 工具, 一个可选标签, 默认、 登录、 退出或删除 .
-   按 Escape 不切换关闭屏幕 .

取接器标记了目前的组织,工具结果记录了它们的起源组织. 切换关闭交互式可视化面板;记录截图仍与旧组织相关.

切换适用于当前 Pi 会话,而不是其他运行的会话. 复会或分会恢复其选择. **默认用于新会话** 改变全局默认; **用于此工程** 写入工程选择。 既未调整现有会话的目标。 如果选中的连接被移除或配置无效,插件会停止而不是默默地选择另一个组织.

切换不会抹去之前的对话结果. 如果您不希望不同组织在同一模式上下文中的结果,则使用单独的Pi会话.

## 工具和诊断

使用 `/datadog toolsets`,或连接屏幕,用于为选定的组织配置工具。 已存在的可搜索拾取器支持服务器默认,所有一般可用的工具,以及明确选择的预览工具.

该代理人有三个工具:

-   `datadog` 为选定的组织发现和引用 MCP 工具.
-   `ddconfig` 报表保存的连接状态;其 `check` 动作探测服务器而不启动交互式登录,及其 `switch` 动作将会话移动到另一个已保存的连接上,这样代理可以在一个提示中比较 orgs .
-   `ddtoolsets` 管理选定连接的工具.

提示还载有Datadog MCP Server对所选组织的指示,如技能和访问指导等. Pi在提示的开头连接来读取它们,如果服务器在数秒内无法被接通,则将其放出.

`/datadog setup` 财务报告和审定财务报表 `/datadog configure` 无参数打开相同的连接屏幕进行兼容。 他们的旧址/镜面论据和单独的 `ddsetup` 工具已删除。 通过用户控制登录和添加组织 `/datadog`; 代理只能切换您已经保存的连接 .

## 可视化面板(macOS)

Datadog图在macOS 13+的Pi互动终端上自动使用ddviz,并配有Xcode命令行工具与Swift 5.7+. 不需要选择进入环境变量。 其他平台和机器缺失了这些先决条件,保留了普通的文本结果而无需警告.

工具链检查只运行在第一个生成图表的回复或一个明文 `/datadog ddviz` 请求,从启动开始。 其结果共享给会话; 确定先决条件后重新启动 Pi 。 只文本响应,工具出错,以及非交互模式不会触发这些检查或启动面板.

生成数据犬图表后,按 **移动+ 右箭头** (Shift) 在 Pi 编辑器中显示交互面板. 这在苹果终端工作. app没有额外的键盘配置,也不与Pi的默认绑定相冲突.

当小组有重点时,按 **逃脱** 或者说 **计算机+W** 关闭它。 移动+ 右箭头没有在那里被截取,所以面板中的文本选择仍然可用.

运行 `/datadog ddviz` 在任何检查本地可视化支持和服务器连接的平台上:

-   **机器先决条件** — macOS, Xcode 命令行工具, Swift
-   **安装** ——插件捆绑的文件
-   **终端** ——内在图像协议支持
-   **运行时间** ——可视化面板的进程是否在运行中
-   **连通性** 选定数据犬组织的可达性

每一个失败的检查 都解释了该怎么做 命令是只读的:它从不启动面板,改变组织,在服务器侧展开控制中签名,或者改变服务器侧展开控制. 连接不确定服务器是否会返回图表;仅文本的回复使用普通渲染. 不运行是正常的稳定状态;运行时间从第一个支持的图表生成工具调用开始.

### 为什么是 Shift+右箭头 ?

快捷键必须在 Apple 终端工作 。 app不附加配置并避免与Pi的默认绑定相冲突,包括仅用于拾取器. 移动+ 右箭能满足两种要求: 被转出箭头有不同的后继终端序列,不同于Ctrl+Shift+字母组合. Pi 编辑器不用于文本选择, 提示显示 **移动QQ** 使箭头键清晰。 用户定义的密钥绑定或其他扩展仍然可以引入冲突.

尝试或评估的替代品:

| 快捷键 | 为何没有保留 |
| --- | --- |
| 缩写+ 移动+O | 原始装订。 Terminal.app发送与Ctrl+O相同的输入,Pi用于扩展/collapse工具输出. |
| 缩写+R | 首次更换,在当地测试. 它在编辑器中有效,但触发了启动冲突警告,因为Pi将其绑定在拾取器中的会话重命名. |
| 备选+O | 未在 Pi 默认中被使用, 但是 Terminal. app 需要启用“ 使用选项作为元密钥 ” ; 否则选项+ O类型一个字符. |
| (简体中文) | 在 Pi 的macOS 默认中可用,但被拒绝,因为它暗示退出而不是显示面板. |
| F6 导弹 | 未在 Pi 的默认中被使用,并由遗留终端支持,但经常需要Mac键盘上的Fn/Globe;偏好非函数键快捷键. |
| 缩写+ 空间 | 可以被macOS输入源切换截取. |
| (简体中文) | 常规地发送终端退出信号,因此其与退出相关的缺点与Ctrl-+Q相同. |

## 存储和项目覆盖

默认状态目录是 `~/.pi/agent/datadog/`,跟随Pi的 `PI_CODING_AGENT_DIR` 设定时覆盖 .

-   `datadog.json` 持有已保存的剖面元数据和默认选择,而不是证书.
-   `datadog-oauth/profiles/<credential-id>/<domain>/credentials.json` 拥有新的OAuth赠款. 证书ID不透明,不依赖显示标签.
-   Pi会话元数据持有会话所选配置文件ID.
-   一个值得信任的项目 `.pi/datadog.json` 可以选择保存的配置文件 `{ "profileId": "<saved-id>" }` 和可选择的覆盖 `toolsets`。它不能重新定义证书或目的地服务器。 这些ID指的是本地保存的连接;它们不是便携式全团队化名.

现有 `{ "domain": "...", "toolsets": "..." }` 配置会自动导入 。 现有的基于域的 OAuth 缓存保留在原地并被写入后升级,而不是复制旋转的刷新符. 一个工作连接仅仅因为插件升级而不需要另一个登录. 当该可信任的项目打开时, 将导入遗留项目覆盖 。 遗留项目无法引入新自定义 MCP 目的地: 明确通过服务器连接 `/datadog` 先说.

签名清除连接的本地存储证书 通过 Pi 会话在这个设备上。 它不会撤销远程 Datadog 的授权,也不会影响其他被保存的猩猩. 删除连接也会删除已保存的元数据 。 挑选项目和会议需要另外挑选.

## API 密钥和无头用法

要使用 API 密钥, 请在启动 Pi 之前设定两个变量 :

```bash
export DD_API_KEY=your-api-key
export DD_APPLICATION_KEY=your-application-key
```

连接屏幕提供 **使用环境的 API 密钥** 当两者都可用时。 此模式被保存在该连接上; 环境密钥永远不会覆盖一个明确保存的 OAuth 连接 。 变量为每个 Pi 进程提供一对密钥,而不是每个被保存的 org 提供不同的一对. 在工具执行前, 经认证的矿石仍然被验证 .

无头运行使用之前配置的连接并缓存 OAuth 证书或环境密钥 。 他们从不等待交互式浏览器登录. 在使用中配置/签名 `/datadog` 在 TUI 模式中首先。 现有的环境键配置在导入后继续工作.

OAuth 回调默认为 `http://localhost:19876/callback`设置 `DD_OAUTH_CALLBACK_PORT` 如果端口被占用, 在启动 Pi 之前 。 登录取消释放回调收听器.

## 安全边界

OAuth使用官方的MCP SDK进行发现,客户端注册,PKCE,并刷新令牌. 执行工具前, 插件验证 `datadog://mcp/whoami` 对抗保存的组织UUID. 没有这种身份资源的服务器在验证可用之前无法被使用.

证书文件在 POSIX 上只使用所有者权限(`0600` 文档, `0700` 目录,原子写作,和跨进程锁定. 它们是文件备份的,没有加密或存储在OS键链中. Windows使用其文件系统ACL模型. 这些措施并不将资质与作为用户运行的其他进程相隔离.

自定义 MCP 域需要在连接设置中明确确认. 只连接到您信任的服务器 。 该插件在其模型化工具结果或会话元数据中不包含证书.

## 更新和支持

更新软件包后运行 `/reload` 在 Pi 中。 连接更改不需要重新启动.

-   [数据犬 MCP 服务器文档](https://docs.datadoghq.com/mcp_server/)
-   [Pi 文档](https://pi.dev/docs)

## 法律

见 [通知](https://npmcn.com/package/%40datadog/pi-plugin/NOTICE), (中文(简体) ), [LICENSE-3rd Party.csv (英语)](https://npmcn.com/package/%40datadog/pi-plugin/LICENSE-3rdparty.csv),则 [数据犬隐私政策](https://www.datadoghq.com/legal/privacy/)。 。 。 .

## 常见问题

### @datadog/pi-plugin 是什么？

通过预配置 Datadog MCP 服务器在 Pi 编码代理中直接使用 Datadog\. 查询日志,度量衡,痕迹,仪表板,以及更多的通过自然对话\.

### 如何安装 @datadog/pi-plugin？

在项目目录运行 npm install @datadog/pi-plugin，或使用 pnpm add / yarn add / bun add。

### @datadog/pi-plugin 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/datadog\_\_pi-plugin 是否存在。

### @datadog/pi-plugin 支持 ESM 还是 CommonJS？

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

### @datadog/pi-plugin 可以商用吗？

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

### @datadog/pi-plugin 的下载量有多少？

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

### @datadog/pi-plugin 还在维护吗？

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