Plandex 安装完全指南一行脚本安装、手动安装与从源码构建【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex本篇技术指南完整讲解开源 AI 编程代理 Plandex 在 Linux/macOS/FreeBSD 及 WindowsWSL下的全部安装方式包括一行命令快速安装、从 Release 手动安装、从源码自行构建以及安装后的首次运行配置、内置自升级机制与开发环境搭建。读完本文你将掌握 Plandex CLI 的完整部署路径并能基于仓库源码理解每一步安装动作背后的实际逻辑。一、安装方式总览Plandex 是一个终端Terminal内的 AI 编程代理其官方文档 docs/docs/install.md 提供了三种安装路径方式适用场景特点一行脚本快速安装绝大多数用户自动探测平台与架构、自动下载二进制、自动放入 PATH、自动创建pdx别名手动安装需要精确控制安装位置从 Release 下载对应平台的压缩包手动放入 PATH从源码构建开发者、需要自定义版本基于 Go 工具链本地编译可注入自定义版本号三种方式最终得到的都是同一个plandex可执行文件附带pdx别名仓库当前版本号为2.2.1见 app/cli/version.txt。二、一行脚本快速安装官方推荐的一行安装命令如下curl -sL https://plandex.ai/install.sh | bash这一行命令执行的实际逻辑就在仓库的 app/cli/install.sh 中。理解脚本内部流程有助于你判断安装失败时问题出在哪里平台探测uname -s支持darwinmacOS、linux、freebsd三种平台。脚本同时识别CYGWIN*/MINGW*/MSYS*为windows但会直接打印「Windows 仅支持 WSL无法在 CMD 或 PowerShell 中工作」并退出安装。架构探测uname -mx86_64对应amd64arm64/aarch64对应arm64即 Apple Silicon 与 ARM 服务器均可直接安装。版本确定优先读取环境变量PLANDEX_VERSION可用于锁定历史版本否则从https://plandex.ai/v2/cli-version.txt拉取最新版本号。下载与解压从 GitHub Release 下载命名规范为plandex_${VERSION}_${PLATFORM}_${ARCH}.tar.gz的压缩包对应 tag 为cli/v${VERSION}解压得到单个plandex二进制。放入 PATH将二进制移动到/usr/local/bin/若权限不足会自动尝试sudo并明确提示「请手动将 plandex 移动到 PATH 中的某个目录」。创建pdx别名如果系统里还不存在pdx命令脚本会为plandex创建符号链接pdx若已存在同名命令则跳过避免覆盖。v1.x 旧版本迁移若检测到已安装的 Plandex 为1.x版本通过plandex version判断脚本会把旧二进制重命名为plandex1、旧别名重命名为pdx1再安装 v2保证新旧版本并存不冲突。安装完成后脚本会提示在任何项目目录下运行plandex或pdx即可开始使用。三、手动安装从 Release 下载二进制如果需要更精细的控制例如放到自定义目录、离线环境安装可以从 Release 页面获取对应平台的二进制放入 PATH 中的任意目录打开 Plandex 的最新 Release 页面找到命名符合plandex_版本_平台_架构.tar.gz的附件。可选的平台与架构组合如下表与 app/cli/install.sh 中的探测逻辑一一对应平台取值说明macOSdarwinIntel 与 Apple Silicon 均支持Linuxlinux主流发行版均可用FreeBSDfreebsd脚本同样探测该平台架构amd64/arm64x86_64→amd64aarch64→arm64解压得到plandex二进制将其移动/复制到PATH中的任意目录如/usr/local/bin、~/bin并赋予可执行权限tar zxf plandex_2.2.1_linux_amd64.tar.gz sudo mv plandex /usr/local/bin/ # 按你的系统实际情况调整可选创建pdx别名与一键脚本行为一致sudo ln -s $(which plandex) $(dirname $(which plandex))/pdx注意Plandex 是纯 Go 单二进制见 app/cli/go.mod模块名为plandex-cli没有额外的运行时依赖手动安装时不需要安装任何其他组件。四、从源码构建如果你希望基于最新主干代码构建、参与开发或注入自定义版本号可以使用官方文档提供的源码构建方式git clone https://gitcode.com/GitHub_Trending/pl/plandex.git cd plandex/app/cli go build -ldflags -X plandex/version.Version$(cat version.txt) mv plandex /usr/local/bin # adapt as needed for your system对这段命令逐项拆解进入 CLI 模块目录仓库中app/cli是一个独立的 Go 模块app/cli/go.modgo 1.23.3它通过replace plandex-shared ../shared引用同级目录app/shared的共享包因此构建时必须位于app/cli目录下。-ldflags注入版本号版本变量的默认值在 app/cli/version/version.go 中定义为development通过-X plandex/version.Version...在链接期覆盖。cat version.txt读出仓库当前版本号目前为2.2.1确保构建出的二进制与 Release 版本号一致。如果你构建的是开发版且不注入版本号plandex version会输出development同时 CLI 会跳过内置的升级检查见下文第六节。安装到系统mv plandex /usr/local/bin按你的系统调整也可放入~/bin等任何 PATH 目录。构建完成后用plandex version验证版本号是否正确注入。五、Windows 用户只支持 WSL官方文档明确强调Plandex only works correctly in the WSL shell. It doesnt work in the Windows CMD prompt or PowerShell.即 Windows 必须通过WSLWindows Subsystem for Linux使用 Plandex先安装并进入 WSL 发行版如 Ubuntu在 WSL shell 内执行第二节的一键安装命令或第三、四节的手动/源码方式之后的plandex、pdx命令均在 WSL shell 中运行。这一限制在 app/cli/install.sh 中有硬性保障当uname -s返回CYGWIN*/MINGW*/MSYS*即 Git Bash、MinGW 等类 Windows 环境时脚本会直接输出「Windows is only supported via WSL」并exit 1防止在不受支持的环境中产生误导性安装。六、安装后的内置自升级机制Plandex CLI 自带自动升级能力这一逻辑实现在 app/cli/upgrade.go并由入口 app/cli/main.go 在每次启动时触发version、browser、help子命令除外。理解它有助于你掌握版本管理版本检查启动时请求https://plandex.ai/v2/cli-version.txt获取最新版本用Masterminds/semver与当前版本做语义化比较请求有 5 秒超时失败时静默跳过不影响正常使用。交互升级检测到新版本后CLI 会提示「A new version of Plandex is available」询问是否升级确认后自动下载对应平台的新版 tarballplandex_${version}_${GOOS}_${GOARCH}.tar.gz借助go-update库原地替换正在运行的二进制随后以相同参数自动重启进程。跳过升级提示设置环境变量PLANDEX_SKIP_UPGRADE1任意非空值即可永久关闭升级检查从源码构建的development版本也会自动跳过。权限问题若当前用户无写权限导致替换失败会提示使用sudo重试。七、首次运行与基础配置安装完成后进入一个项目目录并启动 Plandex REPLcd your-project-dir如果是全新项目官方文档建议先用git init初始化仓库。Plandex 并不要求项目必须在 git 仓库中但若使用 gitPlandex 能与 git 良好集成如自动生成提交信息、可选的自动提交。git init然后启动plandex或使用短别名pdx首次运行时你可能需要处理两件事模型 Provider 的 API Key如果你使用 OpenRouter 等自带 Key 的方式需先导出对应的环境变量例如export OPENROUTER_API_KEY... # 如果使用 OpenRouter.aiClaude Pro/Max 订阅接入如果你拥有 Claude Pro 或 Max 订阅Plandex 在调用 Anthropic 模型时可以直接使用该订阅首次运行时 CLI 会询问是否连接订阅。启动后 CLI 默认进入chat 模式适合在动手写代码前梳理思路当任务明确后Plandex 会引导切换到 tell 模式制定详细计划并开始写代码无参数直接运行plandex即启动 REPL 的入口逻辑见 app/cli/cmd/root.go。八、安装目录与运行数据落盘位置从 app/cli/fs/fs.go 的源码可以确认Plandex 运行时的数据存放遵循如下约定了解这些路径便于排查问题与备份数据路径用途~/.plandex-home-v2/用户主目录生产环境。开发模式下为~/.plandex-home-dev-v2/~/.plandex-home-v2/auth.json认证信息登录态~/.plandex-home-v2/accounts.json账户列表信息~/.plandex-home-v2/cache/tiktokentiktoken 分词缓存目录通过TIKTOKEN_CACHE_DIR注入~/.plandex-home-v2/plandex.log运行日志由 lumberjack 按 10MB 轮转、保留 3 份备份、最长 28 天并压缩归档配置见 app/cli/main.go项目目录/.plandex-v2/每个项目内的 Plandex 状态目录开发模式为.plandex-dev-v2/CLI 会在当前目录向上查找它九、开发环境本地构建与热重载对于想深入源码或做二次开发的读者仓库提供了完整的开发环境搭建方案详见 docs/docs/development.md它同样属于「安装」的延伸场景前置依赖Go 1.23.3与 app/cli/go.mod 声明一致、reflex0.3.1文件监听与自动重建、PostgreSQL 14服务端需要、Python 3LiteLLM 透传代理需要。环境变量设置DATABASE_URLpostgres://user:passwordhost:5432/plandex?sslmodedisable与GOENVdevelopment并确保 PostgreSQL 已运行且建好plandex数据库。运行开发脚本从仓库根目录执行./app/scripts/dev.shLinux 下建议sudo ./app/scripts/dev.sh因为需要复制二进制到/usr/local/bin。该脚本通过 reflex 监听变更同时重建 server 与 CLIserver 默认运行在 8099 端口。开发版命令构建产物会被复制为/usr/local/bin/plandex-dev并创建别名pdxd与生产安装的plandex/pdx互不冲突。输出目录、二进制名、别名分别可用PLANDEX_DEV_CLI_OUT_DIR、PLANDEX_DEV_CLI_NAME、PLANDEX_DEV_CLI_ALIAS覆盖见 app/cli/dev.sh。连接开发 server运行 CLI 时设置PLANDEX_ENVdevelopmentCLI 便会默认连接开发 server并将运行数据写入~/.plandex-home-dev-v2与项目下的.plandex-dev-v2与生产数据隔离。十、常见安装问题速查现象原因与处理脚本提示「Windows is only supported via WSL」在 CMD/PowerShell/Git Bash 中执行了安装请改用 WSL shell提示Permission denied当前用户对/usr/local/bin无写权限脚本会自动尝试sudo也可以把二进制放到~/bin等用户目录并加入 PATHpdx别名未生效系统已存在其他pdx命令脚本为避免覆盖会跳过可手动用ln -s创建构建后plandex version输出development构建时未注入-ldflags -X plandex/version.Version...且该版本不会触发自动升级提示不想看到升级提示设置PLANDEX_SKIP_UPGRADE1旧 v1.x 安装被重命名一键脚本检测到 v1 后会将其改为plandex1/pdx1以并排共存属于预期行为结语Plandex 的安装设计遵循「零依赖、单二进制」原则无论是curl | bash的一行脚本、Release 手动安装还是go build源码构建最终都得到一个可独立运行的 CLI配合 WSL 支持覆盖了 Windows 场景内置的升级检查与开发模式plandex-dev/pdxd则分别服务于日常使用与源码开发。结合本文引用的 app/cli/install.sh、app/cli/upgrade.go、app/cli/fs/fs.go 等源码文件你可以随时回溯每一步安装与运行行为的确切实现。【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考