# @daytona/pi 中文文档

规范地址：https://npmcn.com/package/%40daytona/pi/

版本：0\.191\.2
npm 元数据更新时间：2026-09-30T16:12:36.965Z
中文译文更新时间：2026-11-11T20:09:04.863Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：85.7 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：typebox ^1\.1\.38，@earendil-works/pi-coding-agent \>=0\.79\.0
- 首次发布：2026-06-19T11:44:14.474Z
- 最新版本发布：2026-09-30T16:12:36.545Z
- 近 30 天下载量：3704（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

运行所有工具的 Pi 编码代理扩展名在本地运行时, 在远程、 ephemeral Daytona 沙盒内调用

## 安装

```sh
npm install @daytona/pi
```

也可以使用：`pnpm add @daytona/pi`、`yarn add @daytona/pi`、`bun add @daytona/pi`

## README

# Pi 代托纳沙盒扩展

这是一个Pi扩展 运行每一个Pi工具呼叫 在代顿纳沙盒。 代理在你的机器上运行,而 `bash`,文件 I/O,并在一个远程沙盒中执行搜索,该沙盒是在您使用 Pi 启动时创建的 `--daytona`,保留会话(并在恢复会话时重排),并删除删除会话.

## 特征

-   运行 Pi 的工具呼叫一个孤立的 Daytona sandbox , 而代理在您的机器上
-   克隆你身处的重地 `--repo` 自动进入沙盒
-   将每次会话同步到自己的 GitHub 分支 — 代理执行, 扩展推动
-   每会话保留一个沙盒,并在恢复时重新附着
-   当服务器在沙盒中启动时生成活预览链接

## 使用量

### 安装

首先,安装 Pi :

```bash
npm install -g @earendil-works/pi-coding-agent
```

见 [页:1](https://pi.dev/) 用于其他安装选项.

然后在 Pi 中加入代托纳扩展:

```bash
pi install npm:@daytona/pi
```

> \[注\] 稍后要更新扩展, 请运行 `pi update` —— 说 `pi install` 无法刷新已有的安装 .

### 环境配置

此扩展需要 [代托纳账户](https://www.daytona.io/) 财务报告和审定财务报表 [代托纳 API 密钥](https://app.daytona.io/dashboard/keys) 创建沙盒.

将您的 Daytona API 密钥设定为环境变量( 如您在 shell profile 中) :

```bash
export DAYTONA_API_KEY="your-api-key"
```

扩展还读取了这些可选变量:

-   `DAYTONA_API_URL` ——默认为 `https://app.daytona.io/api`。 。 。 .
-   `DAYTONA_TARGET` - 比如说. `us`。 。 。 .

如果未设置密钥, 且可用 UI, Pi 提示您每会话一次 .

### 运行 Pi

从 git 仓库中运行 Pi :

```bash
cd my-project
pi --daytona
```

扩展复制您在沙盒中的 repo , 并将您的工作同步到 GitHub 分支( 见 [GitHub 分支同步](https://npmcn.com/package/%40daytona/pi/#readme-github-branch-sync)) (中文(简体) ).

或者指向另一个仓库:

```bash
pi --daytona --repo github.com/acme/api --branch dev
```

或跑出git repo 得到一个空白的工作空间.

#### 旗帜

| 旗帜 | 说明 |
| --- | --- |
| `--daytona` | 在代托纳沙盒内运行工具 |
| `--repo <url>` | 复制到沙盒的 Git repo( 默认为您所在的 repo) |
| `--branch <name>` | 要克隆的分支( 默认为您的当前分支) |
| `--snapshot <name>` | 选择 Daytona 快照/ 基本图像 |
| `--public` | 创建公共沙盒, 预览 URL 不需要任何符号 |

#### 斜线命令

皮跑的时候 `--daytona`,可以管理活性沙盒:

-   `/sandbox` ——显示活动沙盒的状况:状态,工作目录,分支,同步状态,及其GitHub分支链接
-   `/github` - 在GitHub开设本届会议的分会
-   `/compare` 打开此会场的分支比较 GitHub 上的视图
-   `/merge` ——将本届会议的分会并入其在 GitHub 上的基地
-   `/pr` 为本届会议分支打开 GitHub 拉动请求

## 如何运作

代理运行在你的机器上。 Pi的工具层是可插接的,因此这个扩展代号取代了代托纳支持的实现 `bash`, (中文(简体) ), `read`, (中文(简体) ), `write`, (中文(简体) ), `edit`,以及 `ls`,外加用于 `find` 财务报告和审定财务报表 `grep`. 脚印是总是可见的信号,工作是远程的.

### 生命周期

-   **每个会话一个沙盒,保持横行.** 一个会话的沙盒被录制 **重新连接** 当你复会时,你的工作和环境将持续下去.
-   **空闲暂停** 15分钟后沙盒(`autoStopInterval`,具有压倒性 `--idle-stop <minutes>`) (中文(简体) ). 它的文件系统被保存; 透明地恢复重新启动它 .
-   **当会话是时删除.** 当您从 Pi 的复选菜单中删除一个会话时, 它的沙盒会在下一次 Pi 启动/出局时收割( Pi 没有会话被删除的钩子, 因此扩展会使其活会话与其沙盒相对应) . 没有自动删除计时器——一个沙盒活到其会话消失为止.
-   **纪念会** (单位:千美元)`--blank` / 没有会话)无法恢复,所以他们的沙盒在退出时被删除.

### GitHub 分支同步

如果你在一个 **github.com (英语)** 通过GitHub CLI重新投放和登录(`gh auth login`),每场会话都有自己的分会,代理的承诺被自动推到那里. 货款来自 `--repo`或者——当你省略它时——是 **从您启动的 Git 工程中检测到 Pi** (数量) `origin` 和当前分支).

-   启动时, 扩展创建 `pi/<short-session-id>` 在 GitHub( 关闭您的当前分支, 或 `--branch`然后把它复制到HTTPS的沙盒里.
-   经纪人 **完成自己的事业** ——它促使在做出改变后作出承诺,而不是推动. 每次转弯后,这些延伸通过代托纳区API向分行承诺。 一个没有新的树枝被跳过.
-   `/merge` 将分支并入其基部 `/pr` 打开拉动请求.
-   **叉子** 在主会话的分会场上启动一个新鲜的沙盒和分支.

所有网络 git 操作( clone/ push) 运行 **沙盒内** 通过代托纳; 主机仅使用 `gh` 来铸造一个符号,并呼叫 GitHub API。 在沙盒中配置了一个临时的 git 身份, 从而承诺在盒子外工作 .

> \[注\] 当你不在github.com repo(或 `gh` 未验证),推力被禁用. 沙盒仍然得到一个本地的git repo,以便代理可以犯罪,但没有任何被推.

### 工具

| 工具 | 它会做什么 |
| --- | --- |
| `bash` (+ 用户) `!`(中文(简体) ) | 在沙盒中运行一个命令; 背景进程( R)`&`别吊死经纪人 |
| `read` | 从沙盒读取文件 |
| `write` | 将文件写入沙盒 |
| `edit` | 编辑一个文件( 下載- 修改- 上传; 保存 Pi 精确匹配的语义) |
| `ls` | 列出一个沙盒目录 |
| `find` | 在沙盒内通过 glob 查找文件( gitignore- aware, 支持路径 globs) |
| `grep` | 在沙盒内搜索文件内容 |
| `preview_url(port)` | 获取一个端口的公开预览 URL—— 启动服务器后代理机调用此功能 |

## 发展

这个包裹住在 [`daytona/integrations`](https://github.com/daytona/integrations) 单重 `packages/pi-extension`并且自成一体——它有自己的 `package.json`,锁定文件,和依赖性(没有工作空间工具).

### 设置

```bash
git clone https://github.com/daytona/integrations
cd integrations/packages/pi-extension
npm install
```

### 开发和测试

要修改扩展名,请在此包中编辑源文件.

> \[注\] 因为 Pi 作为 TypeScript 通过 [吉地语](https://github.com/unjs/jiti),没有建设步骤——皮直接运行源.

#### 从源头运行

删除任何先前安装的复制件( 装入两份使每个工具和旗帜冲突 ) :

```bash
pi list                        # shows installed packages and their exact source
pi uninstall <source>          # e.g. npm:@daytona/pi — use the source shown by `pi list`
```

安装本地目录 :

```bash
pi install .    # add --local to scope it to the current project instead of globally
```

运行 Pi :

```bash
DAYTONA_API_KEY=dtn_... pi --daytona
```

到源代码的编辑在下个运行时生效——不需要重新安装.

或者,不安装而加载一次运行的源 :

```bash
DAYTONA_API_KEY=dtn_... pi -e ./index.ts --daytona
```

#### 测试

```bash
npm run typecheck                 # type-check (tsc --noEmit)
npm run smoke                     # offline: load the extension and check it registers (no API key/network)
npm run test:live                 # end-to-end against real Daytona (needs DAYTONA_API_KEY)
```

### 出版

发布是自动的: 合并此软件包 [请放行](https://github.com/googleapis/release-please) 发布PR标记,并从repo的发布工作流程中发布TypeScript源到npm(公开,有出处)——没有手动发布步骤.

## 项目结构

```
packages/pi-extension/
├── index.ts            # Extension entry point: flags, lifecycle, commands
├── src/                # Daytona-backed tool implementations
│   ├── tools.ts        # Tool registration (sandbox-backed tools + preview_url)
│   ├── auth.ts         # Daytona API key resolution
│   ├── sandbox.ts      # Sandbox resilience layer (auto-restart, exec)
│   ├── ops.ts          # Daytona-backed bash/read/write/edit/ls operations
│   ├── find-tool.ts    # In-sandbox find (ripgrep/find)
│   ├── grep-tool.ts    # In-sandbox grep (ripgrep/grep)
│   ├── github.ts       # Host gh control-plane (token + GitHub API)
│   ├── sync.ts         # Sandbox-side git push (Daytona git API)
│   └── util.ts         # Small shared helpers
├── scripts/            # Offline smoke + live integration tests
├── package.json        # Package metadata (includes the "pi" extensions field)
├── tsconfig.json       # TypeScript config
└── README.md
```

## 许可证

阿帕奇 - 2.0

## 常见问题

### @daytona/pi 是什么？

运行所有工具的 Pi 编码代理扩展名在本地运行时, 在远程、 ephemeral Daytona 沙盒内调用

### 如何安装 @daytona/pi？

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

### @daytona/pi 支持 TypeScript 吗？

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

### @daytona/pi 支持 ESM 还是 CommonJS？

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

### @daytona/pi 可以商用吗？

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

### @daytona/pi 的下载量有多少？

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

### @daytona/pi 还在维护吗？

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