zp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are helping the user manage development projects with

zp

, a Zed project launcher that works across local macOS, Apple Containers, and Fly.io Sprites.

你正在协助用户使用

zp

管理开发项目，

zp

是一款Zed项目启动器，可在本地macOS、Apple容器和Fly.io Sprites上运行。

What zp Does

zp的功能

zp

opens projects in Zed across three backends:

local —
```
~/github/owner/name
```
on macOS
container — Apple Container (macOS 26+), projects at
```
/home/klundstedt/github/owner/name
```
sprite — Fly.io Sprite (remote VM), projects at
```
/home/klundstedt/github/owner/name
```

All backends use the

~/github/owner/name

path convention. New machines are bootstrapped with dotfiles automatically.

zp

可通过三个后端在Zed中打开项目：

local（本地） — macOS上的
```
~/github/owner/name
```
路径
container（容器） — Apple容器（macOS 26+），项目位于
```
/home/klundstedt/github/owner/name
```
sprite（精灵实例） — Fly.io Sprite（远程虚拟机），项目位于
```
/home/klundstedt/github/owner/name
```

所有后端均遵循

~/github/owner/name

路径约定。新机器会自动通过dotfiles完成初始化配置。

Usage

使用方法

zp [owner/name | name] [--backend local|container|sprite] [--machine <name>] [--org <org>]

zp [owner/name | name] [--backend local|container|sprite] [--machine <name>] [--org <org>]

Non-Interactive Commands (Use These)

非交互式命令（推荐使用）

When calling

zp

programmatically, always provide all arguments to avoid TTY prompts:

bash

undefined

以编程方式调用

zp

时，请始终提供所有参数以避免TTY提示：

bash

undefined

Open an existing project (fully specified)

打开现有项目（完整指定参数）

zp owner/name --backend container --machine dev

Create a new container, bootstrap it, clone repo, open in Zed

创建新容器、完成初始化、克隆仓库并在Zed中打开

zp owner/name --backend container --machine new-machine-name

Open locally

在本地打开

zp owner/name --backend local

Open on a sprite

在Sprite上打开

zp owner/name --backend sprite --machine mysprite


When `--machine` names a machine that doesn't exist, `zp` creates it, bootstraps dotfiles, and clones the project — all non-interactively.

zp owner/name --backend sprite --machine mysprite


当`--machine`指定的机器不存在时，`zp`会自动创建该机器、初始化dotfiles并克隆项目——全程无需交互。

Interactive Commands (Require TTY)

交互式命令（需要TTY终端）

These invoke fzf and are only usable when the user is at a terminal:

bash

undefined

这些命令会调用fzf，仅在用户处于终端环境时可用：

bash

undefined

Browse all projects across all backends

浏览所有后端的所有项目

Search by repo name (fzf if multiple matches)

按仓库名称搜索（多个匹配项时使用fzf）

zp gitlake

Search by owner/name (offers to clone if not found)

按owner/name搜索（未找到时会提示克隆）

zp owner/name

Browse projects on a specific backend

浏览指定后端的项目

zp --backend container zp --backend container --machine dev

undefined

zp --backend container zp --backend container --machine dev

undefined

Backends

后端

Backends are plug-in shell scripts in

~/.local/bin/zp-backends/

. Each implements:

Function	Purpose
`backend_available`	Check if CLI is installed
`backend_list`	List machines
`backend_create <name>`	Create a machine
`backend_start`	Start/wake a machine
`backend_ensure_ssh`	Set up SSH, return `user@host[:port]`
`backend_exec <cmd>`	Run a command via native transport

后端是位于

~/.local/bin/zp-backends/

中的可插拔shell脚本。每个后端需实现以下功能：

函数	用途
`backend_available`	检查CLI是否已安装
`backend_list`	列出所有机器
`backend_create <name>`	创建机器
`backend_start`	启动/唤醒机器
`backend_ensure_ssh`	配置SSH，返回 `user@host[:port]`
`backend_exec <cmd>`	通过原生传输方式运行命令

Common Agent Tasks

Agent常见任务

Open a project the user asks about

打开用户询问的项目

bash

undefined

bash

undefined

Determine where it lives, then open it

确定项目位置后打开

zp owner/name --backend container --machine dev

undefined

zp owner/name --backend container --machine dev

undefined

Check what projects exist on a machine

检查某台机器上存在的项目

bash

undefined

bash

undefined

List projects via backend_exec (no SSH needed)

通过backend_exec列出项目（无需SSH）

container exec dev bash -c "find /home/klundstedt/github -mindepth 2 -maxdepth 2 -type d 2>/dev/null"

undefined

container exec dev bash -c "find /home/klundstedt/github -mindepth 2 -maxdepth 2 -type d 2>/dev/null"

undefined

Clone a new repo onto an existing machine

将新仓库克隆到现有机器

bash

undefined

bash

undefined

zp handles clone automatically if the project doesn't exist on the target

如果目标机器上不存在该项目，zp会自动处理克隆操作

zp owner/name --backend container --machine dev

undefined

zp owner/name --backend container --machine dev

undefined

Create a fresh environment for a project

为项目创建全新环境

bash

undefined

bash

undefined

New machine name → creates machine, bootstraps, clones, opens

指定新机器名称→创建机器、完成初始化、克隆项目并打开

zp owner/name --backend container --machine fresh-env

undefined

zp owner/name --backend container --machine fresh-env

undefined

After Opening a New Project

打开新项目后

When

zp

clones a repo that doesn't have an

AGENTS.md

, suggest using the

/bootstrap-project

skill to set up agent context. This gives Claude Code and other agents the project-specific instructions they need to be effective.

当

zp

克隆的仓库中没有

AGENTS.md

文件时，建议使用

/bootstrap-project

Skill来设置Agent上下文。这能让Claude Code及其他Agent获得项目专属指令，从而更高效地工作。

Important Notes

重要说明

GitHub owner in the path (e.g.
```
kylelundstedt
```
) is separate from the OS user (
```
klundstedt
```
).
```
--backend local --machine X
```
is an error — local backend has no machines.
Stopped containers are started automatically. Sprites auto-wake on connection.
Bootstrap runs
```
install.sh --no-prompt
```
from the dotfiles repo on new machines.

路径中的GitHub所有者（例如
```
kylelundstedt
```
）与系统用户（
```
klundstedt
```
）是分开的。
使用
```
--backend local --machine X
```
是错误的——本地后端没有机器概念。
已停止的容器会自动启动。Sprite会在连接时自动唤醒。
新机器初始化时会运行dotfiles仓库中的
```
install.sh --no-prompt
```
脚本。