Plandex Model Roles 全解析：九大 AI 角色分工、职责链路与模型编排配置指南

Plandex Model Roles 全解析九大 AI 角色分工、职责链路与模型编排配置指南【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandexPlandex 是一个面向大型项目和真实世界任务的开源 AI 编码 AgentAI coding agent它并非用单一模型从头到尾完成任务而是将模型调用拆分为多个角色roles每个角色负责一项特定职能再通过模型包model pack统一编排。本篇以官方文档 roles.md 为核心骨架结合仓库源码逐项拆解九个角色的职责、触发时机、可选的 fallback 回退语义以及如何在set-model的 JSON 配置中为每个角色指定模型与参数。读完本文你将能准确理解 Plandex 的模型编排体系并亲手为不同任务阶段配置合适的模型组合。角色总览Plandex 的模型编排分工Plandex 将一次任务拆分为规划 → 上下文加载 → 编码 → 构建 → 汇总 → 命名 → 提交信息 → 自动续跑等环节每个环节由一个独立角色驱动。在源码 app/shared/ai_models_roles.go 中九个角色被统一定义为ModelRole常量并集中登记在AllModelRoles列表中同时通过ModelRoleDescriptions给出官方职责描述角色常量角色 ID官方职责描述ModelRolePlannerplanner回复 prompt 并制定计划replies to prompts and makes plansModelRoleArchitectarchitect基于代码库地图制定高层计划并决定加载哪些上下文makes high level plan and decides what context to load using codebase mapModelRoleCodercoder编写代码以实现计划writes code to implement a planModelRoleBuilderbuilder将计划构建为文件差异builds a plan into file diffsModelRoleWholeFileBuilderwhole-file-builder通过整文件写入方式将计划构建为文件差异builds a plan into file diffs by writing the entire fileModelRolePlanSummarysummarizer对超出max-convo-tokens的对话进行摘要summarizes conversations exceeding max-convo-tokensModelRoleNamenames为计划命名names plansModelRoleCommitMsgcommit-messages编写提交信息writes commit messagesModelRoleExecStatusauto-continue判断是否自动继续执行determines whether to auto-continue说明角色 ID 使用 kebab-case如whole-file-builder、commit-messages、auto-continue而在 JSON 配置文件中对应的键名则采用 camelCase如wholeFileBuilder、commitMessages、autoContinue使用时注意区分。planner总规划师一切任务的起点planner是 Plandex 的主角色main role负责回复用户 prompt 并制定整体计划。它是唯一必选的核心角色其余角色大多围绕它的产出展开。在一次典型任务中planner的输出会先后被architect上下文、coder实现步骤和builder文件构建消费形成一条完整的流水线。planner可选的特性是large context fallback大上下文回退当上下文输入超出当前模型上限时自动切换到回退模型。源码中GetPlannerEffectiveMaxTokens()见 app/shared/plan_model_settings.go体现了其关键计算逻辑func (ps PlanSettings) GetPlannerEffectiveMaxTokens() int { maxPlannerTokens : ps.GetPlannerMaxTokens() maxReservedOutputTokens : ps.GetPlannerMaxReservedOutputTokens() return maxPlannerTokens - maxReservedOutputTokens }即有效可用 tokens 模型最大 tokens − 保留输出 tokens超出该值即触发大上下文回退。例如内置模型包中planner常用anthropic/claude-sonnet-4并为其配置google/gemini-2.5-pro→google/gemini-pro-1.5的多级 large context fallback见 app/shared/ai_models_packs.go以应对超长上下文场景。architect可选的高层架构师与上下文决策者当启用**自动上下文auto-context时architect角色被激活它先利用项目地图project map**制定高层计划再决定为planner提供哪些上下文。也就是说architect是决定喂给主模型什么材料的角色直接影响planner对项目的理解质量。该角色是可选的。当未设置时Plandex 会自动回退到planner角色源码中的回退逻辑清晰可见app/shared/ai_models_data_models.gofunc (m *ModelPack) GetArchitect() ModelRoleConfig { if m.Architect nil { return m.Planner.ModelRoleConfig } return *m.Architect }内置模型包中architect常与planner使用同一档模型如anthropic/claude-sonnet-4因为架构决策同样需要强推理能力在部分模型包中如 OpenAI 推理包architect也使用openai/o3-high这类强推理模型。coder按计划写代码的执行者coder负责在规划阶段planning stage把planner制定的每一步计划落实为实际代码。官方文档特别强调指令遵循instruction-following对coder至关重要因为它必须严格遵守特定的格式规则如结构化编辑、XML 输出格式等才能被后续的builder正确解析并落盘。coder同样是可选角色未设置时回退到plannerapp/shared/ai_models_data_models.gofunc (m *ModelPack) GetCoder() ModelRoleConfig { if m.Coder nil { return m.Planner.ModelRoleConfig } return *m.Coder }由于写码阶段对格式约束要求高内置包中coder多选择指令遵循能力强的模型例如anthropic/claude-sonnet-4、openai/gpt-4.1或deepseek/v3并为部分模型配置 large context fallback 以应对大文件修改。builder与whole-file-builder把计划变成待定文件更新builder负责将planner描述的变更建议构建为待定的文件更新pending file updates——也就是生成精确的 diff。它是最底层的落地角色对输出的结构要求极高。whole-file-builder是builder的补充手段当更精确的定向编辑targeted edits失败时作为回退通过重写整个文件的方式完成同样的构建任务。官方文档明确该角色可选未设置时回退到builder源码同样印证app/shared/ai_models_data_models.gofunc (m *ModelPack) GetWholeFileBuilder() ModelRoleConfig { if m.WholeFileBuilder nil { return m.Builder } return *m.WholeFileBuilder }从内置模型包看builder倾向使用低成本但输出稳定的模型如openai/o4-mini-low、deepseek/r1-hidden而whole-file-builder往往与builder同档或略高因为整文件写入对输出长度与一致性要求更高。summarizer对话摘要器守住上下文预算summarizer的职责非常聚焦当对话长度即将超过max-convo-tokens上限时对已有对话进行摘要压缩从而保证长会话可以持续进行而不被截断。它是 Plandex 长任务稳定运行的内存管家。与其职责匹配summarizer不需要强推理能力内置模型包普遍为其配置轻量模型如anthropic/claude-3.5-haiku。默认采样参数也体现了低随机、求稳定的设计见 app/shared/ai_models_config.gotemperature0.2, topP0.2。auto-continue判断做完了没有auto-continue根据上一次的响应结果判断当前计划是已完成还是应该自动继续执行。它是 Plandex 自动执行autonomy能力的关键一环让 Agent 能够在多步任务中自行推进而不需要每次等待用户确认。同样地它只需要做二值判断因此是典型的低温度角色默认temperature0.1, topP0.1内置包多为其配置廉价快速模型。与之对应的执行状态处理逻辑可见 docs/docs/core-concepts/autonomy.md 中关于自动执行与后台任务的说明。names与commit-messages命名与提交信息的自动化names为计划plans和上下文context自动生成名称省去手动命名的繁琐提升多计划管理时的可读性相关命令可见 docs/docs/cli-reference.md 中的plans、context相关命令。commit-messages为一组待定更新自动生成提交信息commit message配合apply/commit工作流使用让每次提交都有清晰、规范的说明。这两个角色都属于语言生成型任务需要一定的创造性因此默认采样参数最为宽松temperature0.8, topP0.5见 app/shared/ai_models_config.go内置包中通常配置为anthropic/claude-3.5-haiku这类成本低、速度快的模型。角色默认参数与回退链源码级参考各角色默认采样参数Plandex 为每个角色预设了合理的temperature/topP默认值来源于 app/shared/ai_models_config.go 的DefaultConfigByRole角色默认 temperature默认 topP设计意图planner0.30.3规划需平衡创意与稳定architect0.30.3架构决策求稳coder0.30.3代码生成需稳定summarizer0.20.2摘要须忠实builder0.10.1diff 构建必须精确whole-file-builder0.10.1整文件重写必须精确names0.80.5命名需要一点创造力commit-messages0.80.5提交信息可多样化auto-continue0.10.1判断必须确定角色的四类 fallback每个角色除modelId外均为可选都可配置完整的回退链字段定义见 app/shared/ai_models_data_models.go 的ModelRoleConfig其 JSON Schema 见 model-role-config.schema.jsonlargeContextFallback上下文输入超限时切换如planner的典型用法largeOutputFallback输出需要很大时切换如whole-file-builder的典型用法errorFallback主模型调用失败报错时切换提升可靠性strongModel复杂任务时切换到更强的模型。回退可以嵌套回退模型自身还可配置回退且回退引用既可以是裸模型 ID 字符串也可以是完整的角色配置对象——JSON Schema 中通过递归定义的roleRefoneOf字符串或完整角色配置支持这一特性。实战配置用 JSON 编排你的角色阵容角色配置发生在模型设置Model Settings层面通过set-model或set-model default命令编辑 JSON 完成完整语法见 model-settings.md。角色键既可以是裸模型 ID 字符串也可以是带参数的对象以下示例摘自官方文档并保留原貌。基础示例全字符串形式{ planner: anthropic/claude-opus-4, coder: anthropic/claude-sonnet-4, architect: anthropic/claude-sonnet-4, summarizer: anthropic/claude-3.5-haiku, builder: anthropic/claude-sonnet-4, names: anthropic/claude-3.5-haiku, commitMessages: anthropic/claude-3.5-haiku, autoContinue: anthropic/claude-3.5-haiku }进阶示例对象形式 多级回退链{ planner: { modelId: anthropic/claude-opus-4, temperature: 0.7, topP: 0.9, largeContextFallback: google/gemini-2.5-pro }, coder: anthropic/claude-sonnet-4, architect: anthropic/claude-sonnet-4, summarizer: anthropic/claude-3.5-haiku, builder: { modelId: anthropic/claude-sonnet-4, errorFallback: openai/gpt-4.1 }, wholeFileBuilder: { modelId: anthropic/claude-sonnet-4, largeContextFallback: { modelId: google/gemini-2.5-pro, largeOutputFallback: openai/o4-mini-low } }, names: anthropic/claude-3.5-haiku, commitMessages: anthropic/claude-3.5-haiku, autoContinue: anthropic/claude-3.5-haiku }角色配置对象字段速查字段必填说明modelId对象形式下必填使用的内置或自定义模型 IDtemperature否控制随机性0–2默认值随角色不同见上表topP否随机性的替代控制0–1reservedOutputTokens否为输出预留的 token 数直接影响有效上下文上限maxConvoTokens否会话 token 上限主要作用于planner见GetPlannerMaxConvoTokenslargeContextFallback否上下文过大时的回退模型largeOutputFallback否输出需要很大时的回退模型errorFallback否主模型出错时的回退模型strongModel否复杂任务时使用的更强模型配置的完整合法性校验由 model-pack-config.schema.json 与 model-pack-inline.schema.json 提供大多数编辑器可基于这些 Schema 提供自动补全、校验与内联文档。角色与模型包Model Pack的关系单个角色的配置不是孤立存在的而是聚合在**模型包model pack**中。ModelPack结构体app/shared/ai_models_data_models.go将上述角色组装为一个整体其中planner、summarizer、builder、names、commitMessages、autoContinue是必选角色coder、architect、wholeFileBuilder为可选角色nil 时走各自的回退语义。仓库内置了 16 个模型包见 app/shared/ai_models_packs.go 的BuiltInModelPacks覆盖 Daily Driver、Reasoning、Strong、Cheap、OSS、Ollama 本地、Anthropic、OpenAI、Google、Gemini/O3/R1 规划型等多种组合默认模型包为DailyDriverModelPackDefaultModelPack。例如 Daily Driver 包的角色编排为planner用anthropic/claude-sonnet-4带 Gemini 大上下文回退coder用anthropic/claude-sonnet-4带openai/gpt-4.1回退builder用openai/o4-mini-medium带 strong model 回退whole-file-builder用openai/o4-mini-medium。内置包的完整说明见 built-in-packs.md。使用命令速查plandex models查看当前计划各角色使用的模型models命令内部即按角色逐行渲染见 app/cli/cmd/models.goplandex set-model为当前计划选择模型包或编辑角色 JSONplandex set-model default设置所有新计划的默认模型plandex models default查看新计划的默认模型。模型变更属于版本控制与分支的一部分可以随计划一起回滚或在不同分支间切换相关机制见 version-control.md 与 branches.md。更多模型能力自定义模型、本地 Ollama、模型提供方见 custom-models.md、ollama.md 与 model-providers.md。小结Plandex 的九大角色体系把一次 AI 编码任务拆解为可独立配置、可独立回退的模型调用单元planner定方向architect选材料coder写代码builder/whole-file-builder落盘文件summarizer管内存auto-continue掌节奏names与commit-messages负责收尾规范化。理解每个角色的职责边界与回退语义再结合set-model的 JSON 配置和内置模型包你就能为团队或项目量身定制一套既省成本又保证质量的模型编排方案。【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考