Plandex Context Management 完全指南上下文加载、自动管理与智能窗口机制【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandexPlandex 是一个面向大型项目和真实世界任务的开源 AI 编程代理AI coding agent。上下文Context是 Plandex 工作流的核心概念它决定了 LLM 在规划与实现任务时能看到什么。本文以 Plandex 官方核心概念文档为骨架结合仓库源码app/cli/cmd/load.go、app/cli/lib/context_load.go、app/cli/lib/context_auto_load.go 等深入讲解上下文的自动/手动加载模式、项目地图、智能上下文窗口、以及加载、查看、移除、更新上下文的全部 CLI 操作帮助你按成本与精度需求精准掌控 LLM 的输入。什么是 ContextPlandex 的上下文内涵在 Plandex 中Context 指的是 LLM 用来理解并处理你的项目的全部输入材料包括文件files目录directories目录结构布局directory layouts仅文件名URL 网页文本内容图片images笔记notes即简单字符串通过管道pipe灌入的数据Context 永远与某一个 plan 关联——也就是说上下文是计划级plan-level的不同的计划各自维护独立的上下文集合。更重要的是上下文的变更同样受版本控制参见 version-control并且可以像代码一样进行分支参见 branches。这意味着你可以在不同分支上为同一个计划准备不同的上下文组合切换分支即切换上下文这对实验不同技术方案非常有用。从源码实现看上下文被持久化为多种明确的类型见 app/cli/lib/context_load.go 中的shared.ContextFileType、ContextDirectoryTreeType、ContextMapType、ContextImageType、ContextURLType、ContextNoteType、ContextPipedDataType每种类型在加载时走不同的处理分支例如图片会以 base64 编码进请求体URL 会先抓取网页纯文本内容。自动加载 vs 手动加载v2 的默认行为自动加载从 v2 开始Plandex默认自动加载上下文。创建一个新计划时系统会为项目生成一份**项目地图project map**并载入上下文随后 LLM 会依据这份地图和你的提示词prompt自主挑选与任务相关的上下文文件。这种地图引导选择的流程在源码中有直接体现CLI 在set-config开启auto-load-context时会检查当前计划是否已有地图没有则自动调用MustLoadAutoContextMap()见 app/cli/lib/context_auto_load.go 与 app/cli/cmd/set_config.go反之关闭该选项时会自动移除自动加载的地图removeMapIfNeeded见 app/cli/cmd/set_config.go。自动与手动的取舍Tradeoffs自动加载让 Plandex 更强大、更好用但存在三方面代价成本更多上下文 更多 token 消耗聚焦度LLM 自主选上下文可能选入冗余材料稀释注意力输出速度上下文越大首字节输出越慢。如果你在严格控制成本或者你确定任务只涉及一两个文件那么手动加载更合适。切换到手动模式三种方式方式一使用set-auto选择一个禁用 auto-load-context 的自主级别plus或basic等各自主级别定义见 autonomyplandex set-auto plus plandex set-auto basic plandex set-auto default plus # 为所有新计划设置默认值方式二启动 REPL 或创建新计划时使用--plus/--basic标志会自动把配置项设置到对应自主级别plandex --plus plandex new --basic方式三直接设置auto-load-context配置项 为falseplandex set-config auto-load-context false plandex set-config default auto-load-context false # 为所有新计划设置默认值注意set-config支持丰富的布尔值写法如enabled/disabled、true/false、yes/no、1/0等解析逻辑见 app/cli/cmd/set_config.go 的parseBooleanArg。智能上下文窗口管理Smart Context Windowv2 的另一项关键特性是智能上下文窗口管理当计划包含多个步骤时Plandex 会判断每个步骤具体涉及哪些文件并在实现该步骤时只加载这些文件。与自动加载配合时这等效于一个随计划推进动态伸缩的滑动上下文窗口。智能上下文在手动管理模式下同样有效。例如你手动加载了一个含 10 个文件的目录需要对其中每个文件做修改。没有智能上下文时每一步实现都会把全部 10 个文件塞进上下文开启智能上下文后每一步只加载该步实际编辑的那一两个文件。智能上下文在plus及以上自主级别默认启用也可用set-config手动开关plandex set-config smart-context true plandex set-config smart-context false plandex set-config default smart-context false # 为所有新计划设置默认值自动上下文更新Automatic Context Updates当你在 Plandex 之外自行修改了上下文中的文件继续计划前必须先更新这些文件。旧版 Plandex 会在每次文件变更时提示你手动更新v2 起默认自动更新。自动更新在plus及以上自主级别启用也可手动开关plandex set-config auto-update-context true plandex set-config auto-update-context false plandex set-config default auto-update-context false # 为所有新计划设置默认值自主级别矩阵Autonomy Matrix上下文管理相关的三个配置项在不同自主级别下的启用情况如下nonebasicplussemifullauto-load-context❌❌❌✅✅smart-context❌❌✅✅✅auto-update-context❌❌✅✅✅可以看到auto-load-context只在semiv2 全新安装的默认级别与full开启而smart-context与auto-update-context从plus就开始启用。完整的多特性自主矩阵含auto-continue、auto-build、auto-apply、auto-exec等见 docs/docs/core-concepts/autonomy.md。自动与手动混用加载流程对比即使开启了自动加载你仍然可以手动追加额外上下文但两者的处理方式存在差异。先看纯自动加载时各阶段的行为纯自动加载无手动上下文上下文加载阶段初始只加载项目地图。地图连同你的提示词一起被用来挑选相关上下文规划阶段只加载第 1 步挑选出的上下文实现阶段智能上下文若启用再次过滤每个步骤只加载与其直接相关的文件。自动加载 手动上下文上下文加载阶段你手动加载的内容始终包含在内与项目地图并列规划阶段手动加载的上下文无条件加载无论地图选择步骤是否选中它们实现阶段智能上下文若启用对全部上下文手动 自动再次过滤每个实现步骤只加载直接相关的内容。因此在自动加载模式下手动加载文件的价值在于当你确信某些文件必然相关、不想冒险让 LLM 漏选它们时或 LLM 一直选不准正确上下文时。另外能帮助 LLM 做出正确选择的文件如 README、描述项目结构的文档也很适合手动加载。还有一个重要的手动加载使用场景自动加载暂时只能覆盖项目内的文件和图片因此 URL、笔记、管道数据这几类上下文必须手动加载。手动加载上下文plandex load全解手动加载的核心命令是plandex load别名l、add见 app/cli/cmd/load.go。它可以加载文件、目录、目录结构、URL、图片、笔记与管道数据支持以下核心参数参数简写说明--note-n向上下文添加一条笔记字符串--recursive-r递归搜索并加载整个目录--tree-仅加载目录结构只含文件名--force-f强制加载被.gitignore/.plandexignore忽略的文件--detail-d图片细节级别high/low默认high--map-加载文件地图函数/方法/类签名、变量名、类型等加载文件可传入一个或多个文件路径路径相对于当前终端目录plandex load component.ts # 单个文件 plandex load component.ts action.ts reducer.ts # 多个文件 pdx l component.ts # 别名 pdx l支持 glob 模式批量加载plandex load tests/**/*.ts # 加载 tests 及其子目录下所有 .ts 文件 plandex load * # 加载当前目录所有文件也可以使用..引用父目录或兄弟目录中的文件plandex load ../file.go # 加载父目录中的 file.go plandex load ../sibling-dir/test.go # 加载兄弟目录中的 test.go加载目录使用--recursive/-r加载整个目录含所有子目录plandex load lib -r # 加载 lib、其全部文件及所有子目录 plandex load * -r # 加载当前目录及其所有子目录的全部文件在 REPL 中加载文件与目录在 Plandex REPL 中可以用加相对路径的快捷键component.ts # 加载 component.ts lib # 加载 lib 目录及其全部文件与子目录加载目录布局--tree有些任务中LLM 只需要知道项目或项目某部分的结构而不需要看到每个文件的内容。此时可用--tree只加载目录布局——只包含所有文件与子目录的名字含递归plandex load . --tree # 加载当前目录及其子目录的布局仅文件名 plandex load src/components --tree # 加载 src/components 目录的布局从源码看--tree对应ContextDirectoryTreeType实现中会先展开路径再按总大小/条数做部分跳过partial skipping处理超过限制的路径会被记录并在结束时统一提示见 app/cli/lib/context_load.go。加载项目地图--mapPlandex 借助 tree-sitter 为任意目录生成项目地图展示每个文件中的顶层符号——变量、函数、类等。目前支持 30 种编程语言不支持的语言仍会列出文件不带符号确保模型知晓其存在。地图主要用于自动加载时的上下文选择但在手动管理上下文中同样能提升输出质量有了地图LLM 更可能复用你项目里已有的函数并正确调用而不是重新写一个功能相同的函数。plandex load . --map从源码可见--map对应ContextMapType实现相当考究单次只能加载一个地图目录避免 token 超限导致部分加载状态、会向服务端请求缓存的文件地图LoadCachedFileMap、并对文件内容做 SHA 哈希与 token 统计以便后续增量更新见 app/cli/lib/context_load.go 与 app/cli/lib/context_load.go。加载 URLPlandex 可以加载 URL 的文本内容适合引入相关文档、博客文章、讨论帖等plandex load https://redux.js.org/usage/writing-tests # 加载该 URL 的纯文本内容源码中 URL 会经url.FetchURLContent抓取纯文本与文件一样受MaxContextBodySize与总大小上限约束超限同样被跳过并提示见 app/cli/lib/context_load.go。加载图片plandex load ui-mockup.png对大多数支持图片的模型支持 png、jpeg、非动图 gif 与 webp 格式部分模型可能支持更少或更多的格式。图片在加载时会被读取并 base64 编码进请求体并可通过--detail/-d控制细节级别high或low见 app/cli/lib/context_load.go。加载笔记-n笔记就是简单的字符串可视为粘性说明或指令plandex load -n add logging statements to all the code you generate. # 向上下文加载一条笔记笔记的价值在于稳定性长对话会被摘要以保持在 token 限制内这可能导致你提示词中的一些细节在摘要过程中丢失而笔记不会经历这个过程因而在长对话中比普通提示词更显眼、更持久。管道灌入数据可以把其他命令的输出直接管道进上下文npm test | plandex load # 加载 npm test 的输出CLI 通过检查os.Stdin是否为命名管道os.ModeNamedPipe来识别管道输入并归类为ContextPipedDataType见 app/cli/lib/context_load.go。忽略文件处于 git 仓库中时Plandex遵循.gitignore不会加载被忽略的文件也可在任意目录放置.plandexignore文件写忽略模式进一步自定义忽略规则使用--force/-f强制加载被忽略的文件plandex load .env --force # 即使 .env 在 .gitignore 或 .plandexignore 中也会加载源码中忽略检查基于项目路径映射paths.ActivePaths与fs.IsIgnored被忽略的路径会统一汇总并在结束时提示用户见 app/cli/lib/context_load.go。此外加载阶段还会做去重同类型同路径的上下文已存在则跳过与冲突检测checkContextConflicts若发现冲突会自动触发一次计划构建。查看上下文ls与show列出所有上下文plandex lsplandex lsls别名list-context以表格输出每个上下文项序号#、名称、类型、token 数、添加时间、更新时间见 app/cli/cmd/ls.go。当计划开启了自动加载时表格下方还会分别统计Map tokens与Context tokens两类 token 消耗关闭自动加载时则只显示总 token 数。这让你能直观监控上下文的内存占用。查看上下文内容plandex showplandex show component.ts # 查看 component.ts 的内容 plandex show 2 # 查看 plandex ls 列表中第二项的内容show先按名称/文件路径精确匹配若参数是数字则按ls列表中的从 1 开始的序号定位内部转为 0 基索引后取对应上下文的 Id再请求服务端返回正文见 app/cli/cmd/context_show.go。移除上下文plandex rmplandex rm component.ts # 按名称移除 plandex rm 2 # 按 plandex ls 列表中的序号移除 plandex rm 2-5 # 按索引范围移除 plandex rm lib/**/*.js # 按 glob 模式移除 plandex rm lib # 移除整个目录rm别名remove、unload的匹配逻辑相当完善数字参数被解析为序号或区间parseIndices见 app/cli/cmd/rm.go同时支持按名称/路径/URL 精确匹配、按 glob 模式匹配filepath.Match以及沿文件路径向上回溯父目录的匹配——因此plandex rm lib能移除lib/下所有已加载的上下文项见 app/cli/cmd/rm.go。清空上下文plandex clearplandex clearclear一次性删除当前计划、当前分支下的全部上下文项见 app/cli/cmd/clear.go。注意它作用于整个上下文集合使用前请确认你不需要其中的内容。更新上下文plandex update与自动更新如果上下文中的文件、目录布局或 URL 在 Plandex 之外被修改那么下次发送提示词前它们需要被更新。是否自动更新取决于auto-update-context配置项见上文自动上下文更新。也可以随时手动执行更新命令plandex update # 更新上下文中的过期文件update别名u会先获取当前上下文列表与项目路径调用CheckOutdatedContext找出已过期的项再统一执行更新见 app/cli/cmd/update.go。实战建议与注意事项默认就很好用全新安装的 Plandex v2 默认semi级别auto-load-context、smart-context、auto-update-context均开启开箱即得地图选上下文 滑动窗口 自动同步的完整体验省钱/提速场景确定只改一两个文件时切到plus或basic关闭自动加载配合手动load指定文件能显著降低 token 开销并加快响应防漏选场景自动加载下如果 LLM 反复选错上下文手动加载 README、结构说明文档或你确信相关的文件可以让地图选择过程更稳长对话保真需要贯穿整个会话的持久指令如所有生成的代码都要加日志优先用-n笔记而不是普通提示词敏感文件.env等被忽略文件可用--force强制加载但请只在确有需要时使用版本控制视角上下文变更随计划版本化、可分支切换分支或回退版本时可以放心操作上下文不必担心不可恢复。小结Plandex 的上下文管理围绕地图驱动的自动加载与按需手动加载两条主线展开配合智能上下文窗口与自动更新在能力、成本、速度三者间提供了可精细调节的空间。本文覆盖了从概念上下文类型、项目地图、滑动窗口到实操load / ls / show / rm / clear / update 全套命令再到底层实现app/cli/cmd/load.go、app/cli/lib/context_load.go、app/cli/lib/context_auto_load.go的完整链路。相关配置项的默认值参考 docs/docs/core-concepts/configuration.md自主级别细节参考 docs/docs/core-concepts/autonomy.md规划与版本控制机制则分别见 plans 与 version-control。【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考