# @av-pi-studio/cli 中文文档

规范地址：https://npmcn.com/package/%40av-pi-studio/cli/

版本：0\.0\.115
npm 元数据更新时间：2026-11-04T07:06:17.257Z
中文译文更新时间：2026-11-08T11:57:06.275Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：717 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- 首次发布：2026-07-18T12:58:57.939Z
- 最新版本发布：2026-11-04T07:06:16.895Z
- 近 30 天下载量：1784（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：114（近 12 个月 114 个）

## 中文简介

皮·斯图迪奥的工作是开车 [Pi](https://pi.dev/) ——由Earendil所制作的终端编码代理——通过一个管理代理处理,终端,和git工作树的长寿命守护进程,本地或远程进行. 两个客户跟那个守护进程说话: 这个CLI和一个全b

## 安装

```sh
npm install @av-pi-studio/cli
```

也可以使用：`pnpm add @av-pi-studio/cli`、`yarn add @av-pi-studio/cli`、`bun add @av-pi-studio/cli`

## README

# `@av-pi-studio/cli`

皮·斯图迪奥的工作是开车 [Pi](https://pi.dev/) ——由 Earendil 制作的终端编码代理——本地 通过管理代理进程、终端和git的长寿命守护进程 工作树。 两个客户端与守护进程交谈:这个CLI,和一个完整的浏览器UI. `pi-studio` 开始 守护进程让你进入其中之一:

```bash
pi-studio daemon start   # start (or find) a local daemon, print a pairing QR
pi-studio ui             # serve the browser UI, connected to that daemon
```

![Pi-Studio web UI — an agent reading, editing, and running shell commands, each as its own tool-call card](https://cdn.jsdelivr.net/npm/@av-pi-studio/cli@0.0.115/assets/screenshots/chat-workspace.webp)

* * *

## 安装

```bash
npm install -g @av-pi-studio/cli
```

这暴露了 `pi-studio` 二进制 `PATH`如果没有全局安装,则通过:

```bash
npx @av-pi-studio/cli [options] [command] [args]
```

## 快开始

```bash
# log in to a model provider (the `pi` provider needs one before it can run a turn)
pi-studio auth login

# start a local daemon (if one isn't already running) and print a pairing QR code
pi-studio daemon start

# open the full browser UI, pointed at that daemon
pi-studio ui

# ...or stay in the terminal: run an agent, list it, attach to stream live output
pi-studio agent run --provider pi/claude-3-5-sonnet "implement user authentication"
pi-studio agent ls
pi-studio agent attach <agentId>

# target a remote daemon instead of the local one
pi-studio --host workstation.local:6767 agent ls
```

运行 `pi-studio --help` (或 `<command> --help`)为通令树.

## 网络用户界面

`pi-studio ui` 为制作 Pi-Studio 浏览器 UI 服务——一个三栏工作空间(会议于 左边,中间的聊天/平面/代码,右边的文件和git变化)——作为一个静态站点, 不需要单独的安装或构建步骤。 指向任何守护进程, 本地或远程 :

```bash
pi-studio ui                                    # serves on http://localhost:4173, connects to the local daemon
pi-studio ui --ui-port 8080 --daemon-host workstation.local:6767
```

上面拍摄的英雄是真实的:每个工具都叫代理制作(读取/编辑/写作/shell)制作的 自己的卡,有活的diff统计, 在聊天.

在不离开分页的情况下审查它的变化——一个完整的diff视图,逐行:

![Pi-Studio web UI — git changes diff view](https://cdn.jsdelivr.net/npm/@av-pi-studio/cli@0.0.115/assets/screenshots/git-diff.webp)

将工作空间拆分成多个面板——在一个活终端旁边聊天(由 `node-pty`页:1 file, 或另一个会话 —— 并且布局在重新装入时持续 :

![Pi-Studio web UI — split panes with chat and a live terminal side by side](https://cdn.jsdelivr.net/npm/@av-pi-studio/cli@0.0.115/assets/screenshots/split-panes.webp)

每个文件都以完整的语法打开并突出显示 :

![Pi-Studio web UI — syntax-highlighted code viewer](https://cdn.jsdelivr.net/npm/@av-pi-studio/cli@0.0.115/assets/screenshots/code-viewer.webp)

见 [`ui`](https://npmcn.com/package/%40av-pi-studio/cli/#readme-ui) 命令下方的每个旗帜,以及 [`CONTRIBUTING.md`](https://npmcn.com/package/CONTRIBUTING.md#web-ui-dev-server) 如何从源代码运行 UI dev 模式 .

## 全球备选方案

| 旗帜 | 说明 |
| --- | --- |
| `-H, --host <host>` | 守护进程目标——赤色 `host:port`,或带有 `ws://`编号 :`wss://` 或者说 `http://`编号 :`https://` 方案(例如:. `workstation.local:6767`, (中文(简体) ), `https://box.local:6767`(中文(简体) ) |
| `--password <password>` | 密码保护守护进程密码 |
| `--home <dir>` | 覆盖 `$PI_STUDIO_HOME` (用于客户端代号商店) |
| `--pi-home <dir>` | 覆盖 `$PI_STUDIO_PI_HOME` - 捆绑的Pi CLI自己的 `.pi` 配置目录 。 选择 `auth.json` 页:1 `auth` 组读取/写出,并转发给本地发行的守护进程和 `pi-studio pi`。必须先于子命令 |
| `--json` | 将命令输出为 JSON 而不是表格 |
| `-v, --version` | 打印已安装的 CLI 版本并退出 |

**连接解析**数字 : `--host host:port` → `ws://host:port`页:1 `ws://`编号 :`wss://` 使用 URL 现成; `http://`编号 :`https://` 被接受为熟悉并绘制成 `ws://`编号 :`wss://` (守护进程) 是同一端口上升级到WebSocket的HTTP服务器; `wss://`编号 :`https://` 暗指 TLS. 与 没有 `--host`,CLI目标 `ws://127.0.0.1:6767`。 。 。 .

**默认动作** (无子命令) :

-   `pi-studio <path>` ——打开路径作为守护进程上的一个项目.
-   `pi-studio` (bare)——确保本地守护进程运行,再打印成对的QR代码.

## 命令树

### `agent`

| 命令 | 说明 |
| --- | --- |
| `agent run --provider pi/<model> "prompt"` | 创建代理并运行第一个回合 |
| `agent ls` | 列出所有代理 |
| `agent attach <agentId>` | 流出一个特工的现场活动 |
| `agent send <agentId> "prompt"` | 发送后续提示 |
| `agent steer <agentId> "message"` | 引导运行的转弯( 在当前工具呼叫之后) |
| `agent follow-up <agentId> "message"` | 在代理机停止后发送消息 |
| `agent stop <agentId>` | 中断当前转弯 |
| `agent wait <agentId>` | 屏蔽到代理闲置或关闭 |
| `agent logs <agentId> [-n <limit>]` | 打印页面时间表历史 |
| `agent inspect <agentId>` | 打印完整的代理记录 |
| `agent update <agentId>` | 更新模型/模式/思维/标题 |
| `agent archive <agentId>` | 软删除 |
| `agent delete <agentId>` | 难删除 |
| `agent reload <agentId>` | 继续非公开会议 |
| `agent import <sessionRef>` | 通过手柄导入提供者- 本地会话 |

`run`, (中文(简体) ), `ls`, (中文(简体) ), `attach`, (中文(简体) ), `logs`, (中文(简体) ), `send`,以及 `steer` 也工作没有 `agent` 前缀 (单位:千美元)`pi-studio ls`, (中文(简体) ), `pi-studio run …`) (中文(简体) ).

会话管理镜像Pi自己的斜线命令—— `agent session` (/会), `compact`, (中文(简体) ), `new-session`, (中文(简体) ), `resume-session`, (中文(简体) ), `fork`, (中文(简体) ), `fork-messages`, (中文(简体) ), `clone`, (中文(简体) ), `name`, (中文(简体) ), `export`, (中文(简体) ), `model`, (中文(简体) ), `cycle-model`, (中文(简体) ), `last-message`,以及 `commands` (列表扩展/即时/技能);运行 `pi-studio agent --help` 整个集.

提供者光谱剖析( N)`--provider`: `pi/claude-3-5-sonnet` • 供应商 `pi`,型号 `claude-3-5-sonnet`; 裸体 `pi` 仅供货商; `mock` - 免证书的模拟提供者.

### `auth`

| 命令 | 说明 |
| --- | --- |
| `auth login [provider] [--type api_key|oauth] [--api-key <key>]` | 登录到一个模型提供者。 在没有论据的情况下,以互动方式选择一个; `--api-key` 是无头路径 |
| `auth status [--json]` | 显示哪些提供者被配置, 如何配置( api key / oauth) , 以及从何处配置( 存储证书对一个环境内置) |
| `auth logout <provider>` | 删除存储的证书 。 校对:Soup |

这个 `pi` 提供商在运行转弯前需要模型提供者证书. 这是 支持的提供方式之一——无手编辑 Pi's `auth.json`,没有狩猎 `/login` 内部 `pi-studio pi`交互式 TUI :

```bash
pi-studio auth login                          # interactive: filter the provider list, pick, enter key
pi-studio auth login openai --api-key sk-...  # headless — for scripts, CI, Dockerfiles
pi-studio auth status
```

**无本地和守护进程** 不像这里其他的团体, `auth` 从不打开 WebSocket. 这个 写 Pi 的证书商店 `<piHome>/agent/auth.json` (见 `--pi-home`),这是 守护魔的产卵特工读取的精确文件 接下来你增加的证明文件 代理产物没有重启守护进程 。 交互式提示需要 TTY; 使用 `--api-key` 带有 非交互式设置的明确提供者。 秘密从不重复 店里写着 `0600`。 。 。 .

### `daemon`

| 命令 | 说明 |
| --- | --- |
| `daemon start` | 如果一个本地守护进程尚未运行, 将它喷出, 然后打印成对的 QR |
| `daemon stop` | 发送 SIGTERM 到本地守护进程 |
| `daemon restart` | 停止然后启动本地守护进程 |
| `daemon status` | 打印保健+PID |
| `daemon set-password <pw>` | 把密码打入 `$PI_STUDIO_HOME/config.json` |
| `daemon pair` | 为已运行的守护进程打印配对 URL/ QR |
| `daemon rotate-key` | 薄荷一款新配对键盘- 取消以前发布的每个配对链接/ QR |

`pi-studio onboard` (上层)是用于 `daemon start`行为和赤裸裸 `pi-studio` 做同样的事情.

### `relay`

| 命令 | 说明 |
| --- | --- |
| `relay start [--listen <host:port>]` | 注入本地继电器服务器( 默认) `0.0.0.0:7000`),等待健康 |
| `relay stop` | 发送 SIGTERM 到本地中继器 |
| `relay status [--listen <host:port>]` | 在该地址上下打印中继器 |

自备的零知识接力`@av-pi-studio/relay`让客户端到达守护进程 在防火墙/NAT后面——守护进程拨号到它; 查看该软件包的 README 的全部内容 图片。 运行为自己的管理过程, 完全与守护进程生命周期脱钩: 点 a 守护进程通过 `daemon.relay.endpoint` 内 `config.json` (单位:千美元)`PI_STUDIO_RELAY_ENDPOINT` env),没有 通过此命令.

### `pi`

| 命令 | 说明 |
| --- | --- |
| `pi [args...]` | 运行嵌入式 Pi 编码代理 CLI,逐字转发每个参数 |

一个纯粹的通过代理到准确的 `pi` 二进制捆绑在内 `@earendil-works/pi-coding-agent` (同一个守护神产卵)——所以 `pi-studio pi ...` 是一个 取代全球安装 `pi`,没有它的旗帜,子命令,或 互动TUI被重新执行. `pi-studio pi` 单发射互动TUI, 完全一样 赤线 `pi` (自Pi 1.0.0起默认为全屏-) `pi-studio pi --tui-mode regular`,或 `"tuiMode": "regular"` 在皮语中 `settings.json`,保持终端正常回转; `pi-studio pi -p "prompt"` 运行非交互. `--pi-home` (全球备选方案,必须 来之前 `pi` 在命令行上)重定向被捆绑的 CLI `.pi` 配置目录, 跟它一样 用于本地化的守护进程。 回归全球 `pi` 打开 `$PATH` 如果捆绑 依赖没有安装。 永远不要碰守护进程或电线协议.

### `ui`

| 命令 | 说明 |
| --- | --- |
| `ui [--ui-host <host>] [--ui-port <port>] [--daemon-host <host>]` | 将预建的网页客户端 SPA 作为静态站点 |

服务于建筑 `@av-pi-studio/web-client` 乌伊( UI)`dist/web`通过最小的静态文件服务器 SPA倒置——运行时没有vite/dev依赖性,工作来自任何安装形状. `--daemon-host` (回到全球 `--host`预填已打印的 URL `?host=&connect=1` 所以浏览器 选项卡自动连接; 命令本身从未探测或启动守护进程。 块到 `SIGINT`编号 :`SIGTERM`。 。 。 .

见 [网络用户界面](https://npmcn.com/package/%40av-pi-studio/cli/#readme-the-web-ui) 上面为截图.

### `update`

| 命令 | 说明 |
| --- | --- |
| `update [--check]` | 自我更新到最近 `@av-pi-studio/cli` npm上发布的版本 |

贝壳也一样 `npm install -g @av-pi-studio/cli@<version>` 用于安装 CLI 的路径 首先(参见上面的安装),它尊重您的 npm 配置( registry 镜像, auth, 代理)而不是重新实施注册客户端. `--check` 报告更新是否为 可用而不安装任何东西.

### 特征群体

`chat`, (中文(简体) ), `terminal`, (中文(简体) ), `loop`, (中文(简体) ), `schedule`, (中文(简体) ), `permit`, (中文(简体) ), `provider`,以及 `worktree` 是兄弟顶级 命令组( 没有) `feature` 包装,没有 `project` 组 - 打开一个项目是 顶级 `open <path>` 上面显示的命令 :

| 组 | 图标 |
| --- | --- |
| `chat` | `create <name> [--purpose]`, (中文(简体) ), `ls`, (中文(简体) ), `inspect <roomId>`, (中文(简体) ), `post <roomId> <message> [--from]`, (中文(简体) ), `read <roomId> [-n]`, (中文(简体) ), `wait <roomId>`, (中文(简体) ), `delete <roomId>` |
| `terminal` | `ls`, (中文(简体) ), `create [--workspace] [--cwd]`, (中文(简体) ), `capture <slot>`, (中文(简体) ), `send-keys <slot> <data>`, (中文(简体) ), `kill <slot>` |
| `loop` | `run <prompt> [--max]`, (中文(简体) ), `ls`, (中文(简体) ), `inspect <loopId>`, (中文(简体) ), `logs <loopId>`, (中文(简体) ), `stop <loopId>` |
| `schedule` | `create <cron> <prompt>`, (中文(简体) ), `ls`, (中文(简体) ), `inspect <id>`, (中文(简体) ), `update <id> [--cron] [--prompt]`, (中文(简体) ), `pause <id>`, (中文(简体) ), `resume <id>`, (中文(简体) ), `run-once <id>`, (中文(简体) ), `logs <id>`, (中文(简体) ), `delete <id>` |
| `permit` | `ls`, (中文(简体) ), `allow <permissionRequestId>`, (中文(简体) ), `deny <permissionRequestId>` |
| `provider` | `ls`, (中文(简体) ), `models <providerId>` |
| `worktree` | `create <name> [--workspace]`, (中文(简体) ), `ls`, (中文(简体) ), `archive <name>` |

## 把它当作图书馆

CLI的构件也出口给方案用途:

```ts
import { withDaemon } from "@av-pi-studio/cli";

await withDaemon(ctx, opts, async (daemonClient) => {
  // daemonClient is a connected @av-pi-studio/client DaemonClient
});
```

`withDaemon` 解决目标 URL 从 `--host`/ 默认, 连接, 运行您的回调, 然后 断开-处理 `RpcError`s 和与干净的 stderr 输出和非零的连接失败 出口代码沿途.

## 如何跟守护进程说话

CLI 进程从不运行进程内的守护进程/中继代码 —— 它只会说 WebSocket API 驱动已有守护进程 。 它决定 `@av-pi-studio/server`' 's/(b)`@av-pi-studio/relay/server`是因为 通过绝对模块 URL `import.meta.resolve` (从来没有) `await import()`纯为烘焙该 URL 变成离子 `node -e` 它的子进程 `daemon start`编号 :`relay start` 看到了吗 `daemon-control.ts`是因为 `subprocessStarter` 财务报告和审定财务报表 `relay-control.ts`是因为 `subprocessRelayStarter`A级 稳定每台机器 `clientId` 在第一次使用时生成并存储于 `$PI_STUDIO_HOME/client-id`· ; `clientType` 总是 `"cli"`。 。 。 .

## 发展

```bash
npx vitest run packages/cli
```

测试覆盖命令解析、 提供者- spec解析、 流活动格式化、 守护进程控制 状态机器、输出渲染、配对-URL构造以及 `auth` (路径解析, 即时/通知渲染、登录/状态/记录协调)——全部针对注射 `CliContext` (站出输出槽+模拟) `DaemonRuntime`虚构 `AuthRuntime` 和终端I/O),从不真实 产下守护神 从来没有真正的证书店.

## 常见问题

### @av-pi-studio/cli 是什么？

皮·斯图迪奥的工作是开车 Pi ——由Earendil所制作的终端编码代理——通过一个管理代理处理,终端,和git工作树的长寿命守护进程,本地或远程进行\. 两个客户跟那个守护进程说话: 这个CLI和一个全b

### 如何安装 @av-pi-studio/cli？

在项目目录运行 npm install @av-pi-studio/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 pi-studio，可以用 npx pi-studio 直接运行。

### @av-pi-studio/cli 支持 TypeScript 吗？

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

### @av-pi-studio/cli 支持 ESM 还是 CommonJS？

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

### @av-pi-studio/cli 可以商用吗？

@av-pi-studio/cli 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @av-pi-studio/cli 的下载量有多少？

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

### @av-pi-studio/cli 还在维护吗？

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