Plandex 本地开发环境搭建与热重载工作流Development 模式完全指南【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandexPlandex 是一个面向大型项目与真实世界任务的开源 AI 编码代理本文围绕仓库文档 docs/docs/development.md 展开系统讲解如何从零搭建 Plandex 的本地开发环境涵盖依赖安装、环境变量配置、一键启动脚本、reflex 热重载机制以及开发模式下的数据隔离细节。读完本文你将能够在本机跑起「开发服务器 开发版 CLI」的完整链路并理解plandex-dev、pdxd、PLANDEX_ENVdevelopment等开发专用约定背后的实现原理。一、开发环境全景你需要哪些依赖Plandex 开发环境由四类组件构成官方文档给出的版本要求如下组件版本要求用途Go1.23.3编译服务器与 CLI均为 Go 编写reflex0.3.1监听文件变化并触发增量重建实现开发热重载PostgreSQL14后端唯一持久化数据库Python 3无特殊版本限制运行 LiteLLM 透传代理用于接入各类模型后端其中 reflex 是一个文件监听与命令自动重启工具通过 Go 官方包管理器安装go install github.com/cespare/reflexv0.3.1安装完成后务必确认$GOPATH已加入$PATH否则go install生成的二进制无法被 shell 直接找到# 查看当前 GOPATH echo $GOPATH # 如果为空需要手动设置 export GOPATHpath-to-go-folder从源码看app/scripts/dev.sh 启动时会先检测 reflex 是否存在若未安装且$GOPATH为空脚本会直接报错退出并提示先设置 GOPATH若仅缺 reflex则会自动执行go install github.com/cespare/reflexlatest补装。因此提前手动安装 reflex 0.3.1 只是官方文档的推荐版本实际脚本具备一定的自愈能力。二、数据库准备创建plandex数据库开发环境的持久化存储依赖 PostgreSQL 14。确保 PostgreSQL 服务已启动后需要手动创建一个名为plandex的数据库CREATE DATABASE plandex;数据库的连接信息随后通过环境变量提供给服务器Plandex 会在启动时自动执行 app/server/migrations 目录下全部.up.sql迁移脚本从2023120500_init到2025070200_add_org_user_config完成建表与结构演进无需手动执行任何 SQL 初始化。数据库连接的两个可选项除文档推荐的DATABASE_URL之外从 app/server/db/db.go 的实现看服务器还支持用DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME五个独立变量拼接连接串二者至少提供一组即可。此外无论采用哪种方式服务器连接后会自动为连接串追加以下 PostgreSQL 会话参数以保障长时间 AI 任务执行时的稳定性statement_timeout30000单条语句超时 30 秒lock_timeout4000锁等待超时 4 秒timezoneUTCidle_in_transaction_session_timeout90000事务空闲超时 90 秒连接建立后还会打印pg_settings中这四项的实际生效值便于开发时核对。三、环境变量让服务器进入开发模式搭建完数据库后设置两个关键环境变量# 替换为你的真实数据库连接串 export DATABASE_URLpostgres://user:passwordhost:5432/plandex?sslmodedisable export GOENVdevelopmentDATABASE_URL服务器持久化连接地址格式为标准的 libpq 连接串。GOENVdevelopment告诉服务器当前处于开发模式。在 app/server/setup/setup.go 中服务器启动时会检测该变量并打印In development mode.同时在 app/server/db/db.go 中非 production 环境会将数据库连接池调小最大 10 个连接、5 个空闲连接避免开发机资源被占满。四、一键启动运行 dev.sh所有依赖与变量就绪后在仓库根目录执行开发脚本./app/scripts/dev.shLinux 用户由于脚本会将构建好的 CLI 复制到/usr/local/bin通常需要sudo提权sudo ./app/scripts/dev.shmacOS 用户若当前用户对/usr/local/bin具备写权限大多数情况如此直接运行即可只有遇到权限不足时才需要sudo./app/scripts/dev.sh脚本运行后会持续驻留前台它以reflex建立两组文件监听分别在相关源码变化时自动重建服务器与 CLI无需手动反复编译。dev.sh 到底做了什么源码逐段解读app/scripts/dev.sh 是开发工作流的核心其执行逻辑可以拆解为四步第一步准备 Python 运行时。脚本调用同目录下的 app/scripts/litellm_deps.sh该脚本会检查python3是否存在不存在则退出在app/litellm-venv创建 Python 虚拟环境首次运行时按需安装固定版本依赖litellm1.72.6、fastapi0.115.12、uvicorn0.34.1、google-cloud-aiplatform1.96.0、boto31.38.40、botocore1.38.40将 venv 的bin目录加入PATH保证后续启动的 LiteLLM 代理能找到 Python 解释器。LiteLLM 透传代理的作用是把 OpenAI 兼容请求转发到各类模型后端。它由 app/server/main.go 在服务器启动时通过model.EnsureLiteLLM(2)拉起并在服务器关闭时同步回收。第二步确认 reflex 可用。前面提到缺失 reflex 且未设置 GOPATH 会直接报错否则自动安装。第三步注入开发环境变量。脚本自身再次导出覆盖外部设置export DATABASE_URLpostgres://ds:localhost/plandex_local?sslmodedisable export GOENVdevelopment export LOCAL_MODE1注意脚本默认使用本地plandex_local数据库与空密码账号ds这是脚本内置的本地约定。若你的 PostgreSQL 账号密码与之不同要么提前在 shell 中导出的DATABASE_URL脚本中的 export 会覆盖它要么调整脚本中这一行要么让本地账号与脚本默认值对齐。第四步建立两组 reflex 监听器。reflex -r ^(cli|shared)/.*\.(go|mod|sum)$ -- sh -c cd cli ./dev.sh reflex -r ^(server|shared)/.*\.(go|mod|sum|py)$ -s -- sh -c cd server go build ./plandex-server第一组监听cli/与shared/下的 Go 源码.go、.mod、.sum变化时重新构建 CLI第二组监听server/与shared/下的 Go 与 Python 文件变化时重建并重启服务器进程-s参数使服务器监听器在前一个进程退出后才启动新进程避免端口冲突脚本同时注册了SIGTERM/SIGINT陷阱退出时会清理plandex-server相关进程避免残留。五、构建产物plandex-dev与pdxd别名每次 CLI 重建完成后构建脚本 app/cli/dev.sh 会执行如下操作在app/cli下执行go build -o plandex-dev将二进制复制到/usr/local/bin/plandex-dev为它创建符号链接别名pdxd。这样你在任意目录下都可以直接使用plandex-dev或pdxd命令而无需关心构建路径。为什么要用独立的二进制名文档明确强调这是为了与生产安装区分。生产环境安装的是plandex二进制与pdx别名见仓库根目录的安装与自托管文档开发环境使用plandex-dev/pdxd从而避免反复覆盖你已经装好的生产版本。三个可定制环境变量开发构建的三个产物属性均可通过环境变量覆盖环境变量默认值作用PLANDEX_DEV_CLI_OUT_DIR/usr/local/binCLI 二进制与别名的输出目录PLANDEX_DEV_CLI_NAMEplandex-devCLI 二进制文件名PLANDEX_DEV_CLI_ALIASpdxd符号链接别名例如想输出到用户目录而不需要 sudo可以这样运行PLANDEX_DEV_CLI_OUT_DIR$HOME/bin PLANDEX_DEV_CLI_NAMEplandex-dev ./app/scripts/dev.sh六、开发模式服务器默认端口 8099开发服务器默认监听8099端口。该默认值来自 app/server/setup/setup.go 中的PORT环境变量逻辑未设置PORT时回退到8099同时服务器会打印Started Plandex server on port 8099便于确认。从同一文件还可以看到服务器具备完整的生产级细节请求日志中间件跳过/health与/version监控端点其余请求记录方法与耗时请求体大小上限为 1 GB适配大上下文 AI 请求响应头上限 1 MB收到SIGTERM/SIGINT后优雅关闭先等待活跃 plan 完成最长 60 秒再清理残留锁最后执行关闭钩子含 LiteLLM 代理回收。七、客户端开发模式PLANDEX_ENVdevelopment服务器启动后还需要让 CLI 以开发模式运行。运行 Plandex CLI 前设置export PLANDEX_ENVdevelopment该变量会同时影响 CLI 的两个关键行为1. API 地址指向本地开发服务器。在 app/cli/api/clients.go 中CLI 初始化时会判断PLANDEX_ENV开发模式下CloudApiHost默认取http://localhost:8099与开发服务器端口严格对齐生产模式则指向云端 API。开发模式下还可用PLANDEX_API_HOST覆盖该地址例如服务器跑在别的机器或端口时。2. 数据目录与生产完全隔离。在 app/cli/fs/fs.go 中可以看到目录选择逻辑全局状态目录开发模式使用~/.plandex-home-dev-v2生产使用~/.plandex-home-v2项目状态目录开发模式使用当前目录下的.plandex-dev-v2生产使用.plandex-v2。这意味着你可以并行安装生产版与开发版 CLI两者的登录态、项目上下文互不干扰——这也是官方刻意使用不同二进制名的深层原因不仅命令名隔离连磁盘数据也完全隔离。另外CLI 的本地登录流程同样默认指向开发服务器在 app/cli/auth/account.go 中选择本地登录时默认 Host 即为http://localhost:8099与PLANDEX_ENVdevelopment的默认 API 地址保持一致。八、常见问题排查清单以下结论均可从源码得到验证供搭建时对照排查reflex: command not found$GOPATH未加入$PATH或 reflex 未安装。先echo $GOPATH确认再执行go install github.com/cespare/reflexv0.3.1。Error: GOPATH is not setapp/scripts/dev.sh 在检测到 reflex 缺失且 GOPATH 为空时会直接退出按文档设置export GOPATHpath-to-go-folder后重试。数据库连接失败确认 PostgreSQL 14 已启动、plandex数据库已创建若使用脚本默认的postgres://ds:localhost/plandex_local需要本机存在无密码可用的ds账号或用自定义DATABASE_URL覆盖。CLI 连不上服务器确认服务器已监听 8099日志中有Started Plandex server on port 8099且 CLI 进程环境中有PLANDEX_ENVdevelopment如需改地址设置PLANDEX_API_HOST。构建产物没有更新确认改动文件位于 reflex 监听范围内——CLI 侧是cli|shared下的 Go 文件服务器侧是server|shared下的 Go/Python 文件修改根目录其他文件不会触发重建。九、深入阅读指引如果你希望进一步理解开发模式背后的机制可以沿着以下路径继续阅读仓库源码开发启动脚本app/scripts/dev.sh 与 Python 依赖脚本 app/scripts/litellm_deps.shCLI 构建与产物部署app/cli/dev.sh服务器启动与优雅关闭app/server/setup/setup.go、入口 app/server/main.go数据库连接与迁移app/server/db/db.go 及 app/server/migrationsCLI 开发模式下的 API 地址与目录隔离app/cli/api/clients.go、app/cli/fs/fs.go本地开发模式与完整自托管部署之间存在一些差异如LOCAL_MODE相关行为如需在生产环境自行部署服务器可进一步参考 docs/docs/hosting/self-hosting/local-mode-quickstart.md 与 docs/docs/hosting/self-hosting/advanced-self-hosting.md。至此一套「源码改 → reflex 自动重建 →plandex-dev即时可用」的开发闭环便完整跑通了。【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考