Plandex Plan 全面指南创建、切换、归档与项目目录管理【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandexPlandex 是一个面向大型项目与真实世界任务的开源 AI 编码代理AI coding agent而plan计划是 Plandex 中最核心的工作单元。本指南将以 plans.md 为主体结合仓库 CLI 源码系统讲解 plan 的概念、创建方式、命名与 draft 规则、列表与当前 plan 的切换、删除与归档以及.plandex目录和项目子目录规划等完整实战方案帮助你高效组织多任务、多分支的 AI 编码工作流。什么是 Plan在 Plandex 中plan 相当于 ChatGPT 或 Claude 里的一次对话conversation。它既可以只包含一条 prompt 和一次模型响应、完成一个很小的任务也可以是一次漫长的、与模型来回多轮的完整协作过程最终生成几十个文件、构建出一个完整功能甚至整个项目。一个 plan 聚合了三类核心内容Context上下文你或模型加载的任何上下文包括文件、目录、URL、图片等Conversation对话你与模型之间的全部对话记录Pending changes待应用更改在对话过程中累积起来的、尚未应用到工作区的更改。此外plan 原生支持版本控制与分支branches这意味着同一个 plan 可以像 git 一样在不同的分支上演化随时回退、比较或切换到其他分支继续开发。Plan 在源码中的落点从服务端数据模型看plan 由服务端数据库统一存储与维护CLI 通过 API 与之交互。例如在 app/cli/cmd/new.go 中plandex new会调用api.Client.CreatePlan(lib.CurrentProjectId, shared.CreatePlanRequest{Name: name})在服务端创建 plan 并拿到其 ID在 app/cli/cmd/plans.go 中plandex plans通过api.Client.ListPlans(projectIds)拉取 plan 列表。也就是说plan 的数据并不只存在于本地而是作为项目project下的实体被持久化在服务端。创建新 Plan创建 plan 之前需要先进入项目目录。如果是从零开始的新项目先创建目录mkdir your-project-dir cd your-project-dir通过 REPL 创建直接运行plandex如果当前目录此前没有创建过 planREPL 启动时会自动创建一个新 plan。如果 REPL 中已经加载了某个 plan可以用\current查看则通过\new开启新 plan。通过 CLI 创建plandex newnew命令在源码中对应 app/cli/cmd/new.go 的newCmd并注册了别名n。它的完整工作流程是解析账号与组织auth.MustResolveAuthWithOrg解析或创建项目lib.MustResolveOrCreateProject并行发起两个请求创建 planCreatePlan与获取默认 plan 配置GetDefaultPlanConfig将新 plan 写入本地为「当前 plan」lib.WriteCurrentPlan并把当前分支设为mainlib.WriteCurrentBranch(main)若未指定名称plan 默认命名为draftapp/cli/cmd/new.go若配置开启了自动加载上下文AutoLoadContext则立即对--context-dir指定的目录做一次「仅定义」级别的自动上下文加载app/cli/cmd/new.go。可以看到new不仅创建 plan还会顺带完成当前 plan / 当前分支的本地状态写入与自动上下文加载让新 plan 立即可用。new 命令的实用参数从 app/cli/cmd/new.go 的 flag 定义可以整理出new支持的参数参数说明默认值-n, --name新 plan 的名称不传则自动命名为draft空即draft--context-dir开启自动上下文加载时从哪个目录作为基准加载上下文.当前目录Plan 名称与 Draft 规则创建 plan 后Plandex 会在你发送第一条 prompt 之后根据内容自动为 plan 命名当然你也可以在创建时就指定名称plandex new -n foo-adapters-component如果不预先指定名称plan 会一直叫draft直到你发送初始 prompt 才会获得自动生成的正式名称。Draft 的唯一性约束为了保持整洁同一时间只允许存在一个名为draft的活动 plan。如果你创建了新的 draft plan之前存在的 draft plan 会被自动移除。这一规则意味着「draft」是临时占位名正式命名后才算真正开始一个长期任务。结合源码可以进一步印证服务端在创建 plan 时对应shared.CreatePlanRequest{Name: name}接收名称当name为空时 CLI 侧直接以draft兜底app/cli/cmd/new.go而「仅一个 draft」的约束由服务端在保存 plan 时执行——创建新 draft 时会清理旧 draft。列出 Plan当项目中积累多个 plan 后使用plans命令查看plandex plans该命令在 app/cli/cmd/plans.go 中定义注册了别名pl并支持-a, --archived参数用于只列出已归档的 plan。从源码app/cli/cmd/plans.go可以看到列表输出远比字面上丰富当前目录的 plan 表以表格展示序号#、名称、更新时间、当前分支、上下文 token 数与对话 token 数当前 plan 会用绿色高亮并标记父目录中的 planplans会通过fs.GetParentProjectIdsWithPaths找到上级目录里存在的项目以树状结构展示子目录中的 plan通过fs.GetChildProjectIdsWithPaths带 500ms 超时找到下级目录里的项目并展示输出底部还会给出new、cd、delete-plan、archive、plans --archived等快捷命令提示。也就是说plandex plans是从「当前目录出发、向上下两个方向」搜索整个项目层级中的所有 plan而不是只显示当前目录这正是文档「Project Directories」一节所述能力的实现基础。当前 PlanCurrent PlanPlandex 的大多数命令都针对当前 plan执行因此弄清楚「某个目录下当前是哪个 plan」非常重要。查看当前 planplandex currentcurrent命令app/cli/cmd/current.go会拉取当前 plan 的详细信息并以表格展示当前 plan 名称、更新时间、创建时间、分支、上下文 token 与对话 tokenapp/cli/lib/current.go。切换当前 plan 使用cd命令plandex cd # 从列表中选择一个 plan plandex cd some-other-plan # 按名称切换到指定 plan plandex cd 2 # 按 plandex plans 列表中的序号切换cd命令别名set-plan见 app/cli/cmd/cd.go的实现细节值得注意不传参数时通过交互式列表选择term.SelectFromList传参时先尝试解析为数字序号strconv.Atoi序号范围在1..len(plans)之间才有效解析失败则按名称精确匹配选定后调用lib.WriteCurrentPlan把 plan ID 写入本地状态文件再调用lib.MustLoadCurrentPlan重新加载当前 plan同时恢复该 plan 的当前分支还会异步调用api.Client.SetProjectPlan把当前 plan 同步到服务端用于新设备首次使用时的状态恢复app/cli/cmd/cd.go。当前 plan 的本地持久化机制「当前 plan」不是凭空存在的状态它被持久化在用户的本地 Plandex 目录中。相关实现见 app/cli/lib/plans.go 与 app/cli/lib/current.go项目级状态.plandex/projects-v2.json记录当前项目 ID按账号区分计划级状态~/.plandex/projectId/current-plans-v2.json记录当前 plan ID按账号区分见 app/cli/lib/plans.go 的WriteCurrentPlan/ClearCurrentPlan分支级状态~/.plandex/projectId/planId/settings-v2.json记录每个 plan 当前的 branch默认main见 app/cli/lib/plans.go 的WriteCurrentBranch。这些状态文件都以用户 ID 为键意味着同一台机器上多个 Plandex 账号可以各自维护独立的当前 plan / 分支。删除 Plan使用delete-plan命令删除 planplandex delete-plan # 从列表中选择要删除的 plan plandex delete-plan some-plan # 按名称删除 plandex delete-plan 4 # 按 plandex plans 列表中的序号删除delete-plan别名dp见 app/cli/cmd/delete_plan.go的能力比文档字面描述的更强从源码app/cli/cmd/delete_plan.go可以整理出四种删除方式方式示例说明交互选择plandex delete-plan弹出列表供选择数字序号plandex delete-plan 4按列表序号删除名称精确匹配plandex delete-plan some-plan按名称删除通配符模式plandex delete-plan foo-*使用path.Match匹配多个 plan序号区间plandex delete-plan 1-3删除一段范围内的多个 plan全部删除plandex delete-plan --all删除当前项目全部 plan删除前会列出待删除的 plan 并要求交互确认term.ConfirmYesNo确认后才逐个调用api.Client.DeletePlan执行删除如果删除的正是当前 plan还会调用lib.ClearCurrentPlan清空本地当前 plan 状态app/cli/cmd/delete_plan.go。归档 Plan对于暂时不做了但想保留的 plan可以归档而不是删除。归档后的 plan 不会出现在plandex plans的常规列表中。plandex archive # 从列表中选择要归档的 plan plandex archive some-plan # 按名称归档 plandex archive 2 # 按 plandex plans 列表中的序号归档 plandex unarchive # 从列表中选择要恢复的 plan plandex unarchive some-plan # 按名称恢复 plandex unarchive 2 # 按 plandex plans --archived 列表中的序号恢复查看当前目录下已归档的 planplandex plans --archived从源码看archiveapp/cli/cmd/archive.go与unarchiveapp/cli/cmd/unarchive.go的参数解析逻辑与cd一致不传参数时交互选择传参时优先按数字序号、其次按名称匹配。归档列表接口为api.Client.ListArchivedPlans归档/恢复接口分别为api.Client.ArchivePlan/api.Client.UnarchivePlan。plans --archived输出同样是一张「序号 / 名称 / 更新时间」的表格app/cli/cmd/plans.go。.plandex 目录在任何目录中第一次运行plandexREPL或plandex new时Plandex 会在此目录创建一个.plandex目录用于存放轻量级的项目级配置。从源码看.plandex目录的核心职责包括记录项目与 Plandex 服务端的映射.plandex/projects-v2.json保存当前项目 ID见 app/cli/lib/current.go 的mustInitProject与~/.plandex主目录配合项目级状态存于项目内.plandex/账号级状态当前 plan、分支存于用户主目录~/.plandex/下自动上下文加载时会以.plandex所在目录为基准扫描项目文件。多人协作的两种推荐做法提交.plandex目录并让所有协作者加入同一个 org这样大家共享同一套项目映射与协作语义或者把.plandex/加入.gitignore避免把个人状态提交进代码仓库。注意在 app/cli/fs/paths.go 的skipDirs列表中.plandex、.plandex-dev、.plandex-v2等目录都被显式排除在项目文件扫描范围之外避免 Plandex 的元数据被当作上下文加载给模型。在项目子目录中创建 Plan前文默认你是在项目根目录运行plandex或plandex new这也是最常见的用法。但在项目子目录中创建 plan 同样非常有用原因有三缩短上下文路径Plandex 中上下文文件路径是相对于创建 plan 时的目录解析的。如果某个 plan 只关注项目的一部分在子目录中创建 plan加载上下文、在 prompt 中引用文件时路径都会更短、更直观。缩小自动上下文加载范围使用自动上下文加载时在子目录启动 plan或 REPL能限制 project map 的大小并限制模型可加载的文件范围——模型只会在该子目录及其规则范围内发现和加载文件从而节省 token 并让模型更聚焦。便于组织大量 plan当 plan 数量很多时按子目录分区存放更易管理。层级感知的plans列表plandex plans除了显示当前目录的 plan还会显示附近父目录和子目录中的 plan实现见 app/cli/cmd/plans.go 中对父/子项目 ID 的并发查询与树状渲染。这样无论 plan 散落在项目层级的哪个位置你都能看到它们并知道其所在路径。想切换到其他目录下的 plan 时先cd到那个目录再运行plandex cd选择即可。小结Plan 生命周期与常用命令速查场景命令进入项目目录cd your-project-dirREPL 中自动创建 / 新建plandex/\newCLI 创建可指定名称plandex new/plandex new -n name列出含父/子目录plandex plans列出已归档plandex plans --archived查看当前 planplandex currentREPL 中用\current切换当前 planplandex cd [名称\|序号]删除 planplandex delete-plan [名称\|序号\|模式\|区间]归档 / 恢复plandex archive [名称\|序号]/plandex unarchive [名称\|序号]掌握 plan 的创建、命名、切换、删除与归档再结合版本控制、分支与上下文管理就能在大型项目上以清晰、可控的方式并行推进多个 AI 编码任务。【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考