跳到主要内容

数据截至 (上游 commit e2d772072efa)

这是什么 · 全景图 · 阅读地图

30 秒导读: Plandex 是一个跑在终端里的 AI 编码 agent。你用自然语言把任务"告诉"(tell)它,它会规划(拆成多个步骤)再执行(逐个文件写改动),但改动不会直接写进你的项目——它们先进入一个差异沙箱(像 git 暂存区),你审阅 diffs、满意了再 apply 落盘。专为"大项目、大文件、多步骤"设计。

1. 这是什么(零基础也能懂)​

一句话定义​

Plandex 是一个终端里的、能"先规划再执行"跨数十文件大任务的 AI 编码 agent。 它把"和模型聊"变成"让模型真的动手改代码",而且把改动关进沙箱,等你点头才落地。

解决什么问题 / 给谁用​

想象你在终端里,想让 AI 帮你在一个几十万行的真实项目里加一个功能——要改十几个文件、跑好几步、还不能把现有代码搞乱。直接把整个项目塞给模型,要么超出上下文窗口,要么模型改得一团糟、你也不敢应用。

Plandex 就是冲着这个场景来的。README 里点明它主打三件事:

面向的痛点Plandex 的做法
大项目(几十万行、放不进上下文)tree-sitter 生成项目地图,只按需加载相关文件(号称 2M token 有效上下文)
大文件 / 复杂改动结构化编辑 + 多层校验与 fallback,保证 diff 正确
多步骤任务(一个需求要改十几处)把 prompt 规划成子任务,逐个执行,可自动调试
不敢让 AI 直接改所有改动先进 diff 沙箱,人审 apply 后才落盘,可随时 rewind

给谁用:在终端工作、需要 AI 处理"大到别的工具会卡"的编码任务的开发者。

它能做什么(功能)​

  • 规划 + 执行:把一句 prompt 拆成多步计划并逐步写代码(全自动或分步审阅)。
  • 智能上下文:tree-sitter 项目地图 + 按需自动加载相关文件。
  • 多模型编排:混用 Anthropic / OpenAI / Google / 开源模型,按"角色"分工。
  • diff 沙箱 + 版本控制:改动待审、可回滚、可分支、可对比不同模型的结果。
  • 自动调试:跑构建 / 测试 / lint,失败自动尝试修复;装了 Chrome 还能调浏览器应用。
  • REPL + CLI:既能交互式聊,也能脚本化、管道喂数据。

用起来什么样(最小示例)​

下面是一段最小的命令行交互——感受"tell → diffs → apply"这条主线:

cd your-project-dir      # 进到你的项目目录
plandex new              # 开一个新 plan(也可直接跑 `plandex` 进 REPL)
plandex tell "给用户表加一个 email 字段,并更新相关的迁移和校验"
                         # ↑ 模型开始规划 + 逐个文件生成改动(流式回传)
plandex diffs            # 审阅沙箱里累计的 diff(改动还没碰你的真实文件)
plandex apply            # 满意了,把沙箱改动一次性落盘(可选自动 git 提交)

plandex new 定义在 app/cli/cmd/new.go;tell 定义在 app/cli/cmd/tell.go(命令别名 t);diffs、apply 分别在 app/cli/cmd/diffs.go、app/cli/cmd/apply.go。

一句话直觉​

把 Plandex 想成"会自己动手的结对程序员 + 一个 git 暂存区"。 它像同事一样规划并写代码,但每一处改动都先放进"暂存区"给你 review,你不 apply 就不会动你的工作树。这层沙箱,是 Plandex 和"直接改文件"式工具最大的区别。

2. 顶层全景(它大概怎么转)​

怎么读这张图​

从左到右是一次请求的控制流:你在 CLI 敲命令,CLI 把请求发给 Server,Server 是"规划 / 构建的大脑",它通过一个 LiteLLM 代理去调各家模型;shared 包是 CLI 和 Server 共用的数据模型 / token 计数 / 模型配置。

   你(终端)
     │  plandex tell "…"
     ▼
┌──────────────────────┐        HTTP / SSE 流         ┌──────────────────────┐
│  CLI  (app/cli)      │  ───── tell / build ─────▶  │  Server (app/server) │
│  · 交互 / REPL        │  ◀──── diff 流式回传 ─────   │  · 规划(Tell 循环)   │
│  · diff 沙箱 + git    │                             │  · 构建(build→diff)  │
│  · main.go           │                             │  · routes/handlers    │
└──────────────────────┘                             └───────────┬──────────┘
            ▲                                                     │ 模型调用
            │  两端共享数据模型 / token / 模型配置                  ▼
            │                                          ┌──────────────────────┐
   ┌────────┴─────────┐                                │ LiteLLM proxy        │
   │ shared (app/shared)│ ◀────────── 共用 ───────────  │ litellm_proxy.py     │
   │ Context/Plan/roles │                                └───────────┬──────────┘
   └──────────────────┘                                             │
                                                                    ▼
                                            Anthropic · OpenAI · Google · 开源模型

部件一句话职责​

部件干什么在哪
CLI命令 / REPL 交互,管理本地 diff 沙箱与 git 集成,把请求发往 serverapp/cli,入口 app/cli/main.go
CLI 命令每个子命令(new/tell/diffs/apply/rewind…)一个文件app/cli/cmd/*.go
CLI 执行层客户端侧的 Tell/Build 调度、apply 执行app/cli/plan_exec/{tell.go,build.go,apply_exec.go}
Server规划与构建的"大脑",托管 HTTP API,驱动模型app/server,入口 app/server/main.go
路由表把 URL 映射到 handler(含流式的 tell/build)app/server/routes/routes.go
Server handlers每类资源一组处理函数(plans / context / exec…)app/server/handlers/*.go
规划 / 构建核心Tell 循环、build 流水线、racing、结构化编辑app/server/model/plan/*.go
LiteLLM proxy统一各家模型 API 的 Python 代理(含 Claude 订阅 OAuth 头改写)app/server/litellm_proxy.py,由 model.EnsureLiteLLM 拉起
shared两端共享的数据模型(Context/Plan/结果)、token 计数、模型 / 角色 / 包配置app/shared/*.go

主线走一遍(高层,不进代码)​

一次 plandex tell "…" 的旅程:

  1. CLI 发起 — tell 命令(app/cli/cmd/tell.go)解析 prompt 与 flag,经 plan_exec.TellPlan(app/cli/plan_exec/tell.go:26)把请求 POST 到 server。
  2. 进入服务端 — 路由 .../tell(app/server/routes/routes.go:162,标记为 isStreaming=true)命中 handlers.TellPlanHandler(app/server/handlers/plans_exec.go:23)。
  3. 规划(Tell) — server 的 model/plan 里 Tell 循环把 prompt 拆成子任务、组织上下文、生成"要怎么改"的计划(详见 01)。
  4. 构建(build) — 计划里的每处改动被"构建"成具体的文件 diff,期间可多路竞速、结构化编辑、校验修复(详见 02)。
  5. 流式回传 — diff 通过流式响应实时传回 CLI,落进本地沙箱(暂不碰真实文件)。
  6. 人审 → apply — 你 diffs 看改动、apply 落盘、或 rewind 回退(详见 05)。

3. 阅读地图(建议顺序)​

Plandex 体量大,拆成 5 章。建议按 01 → 05 顺序读——正好沿着"一个 prompt 从规划到落盘"的主线由浅入深:

顺序章节讲什么适合什么时候读
0index.md(本章)这是什么 · 架构全景 · 导航先读,建立大盘认知
101-tell-loop.md规划与执行主循环(Tell):prompt 如何拆子任务、逐步实现想懂"大脑怎么想"
202-build-apply.md从模型输出到文件 diff:构建与应用流水线想懂"话怎么变成 diff"
303-context-maps.mdtree-sitter 项目地图 + 按需自动上下文想懂"大项目怎么放得下"
404-models-roles.md多模型编排:角色与模型包想懂"多个模型怎么分工"
505-diff-sandbox-cli.md差异沙箱与 CLI 工作流(人审边界)想懂"人和 AI 的边界在哪"

给 AI agent 的选章提示: 想改"规划怎么分阶段/子任务"→ 读 01;想懂"模型文本怎么变成 diff、为什么可靠"→ 读 02;调"上下文放不下/加载太多"→ 读 03;换模型/配兜底 → 读 04;碰"改动没落地/怎么回滚"→ 读 05。

4. 巧妙之处清单(每条一句,指向对应章)​

Plandex 值得带走的设计精华,先在这里一句话点破,细节各归其章:

  • 多路竞速构建:同一处改动同时跑多个构建尝试,取先成功的,兼顾速度与可靠性 —— 见 app/server/model/plan/build_race.go,详解在 02。
  • tree-sitter 结构化编辑锚点:用语法树(而非纯文本行号)定位"改哪一段",30+ 语言,抗漂移 —— 见 app/server/syntax/structured_edits_tree_sitter.go,详解在 02 / 03。
  • 按需自动上下文:项目地图先给"骨架",再按任务自动只加载相关文件,大项目也放得下 —— 见 AutoLoadContextHandler(app/server/routes/routes.go:200)与 app/server/model/plan/tell_context.go,详解在 03。
  • 角色化多模型:planner / coder / builder / whole-file-builder… 每个角色配不同模型,按活儿分工 —— 见 app/shared/ai_models_roles.go:6 起的 ModelRole,详解在 04。
  • diff 沙箱与 rewind:改动先入沙箱、人审后 apply,全程可回退到任意版本 —— 见 RewindPlanHandler(app/server/routes/routes.go:150)与 GetPlanDiffsHandler(:141),详解在 05。

5. 顶层代码地图​

这张表是"从零切入 Plandex"的跳转索引;更细的符号级地图在各章末尾。

主题文件路径符号 / 锚点
CLI 入口(依赖注入、日志、启动)app/cli/main.goinit、main
CLI 命令根app/cli/cmd/root.goRootCmd
开新 planapp/cli/cmd/new.gonewCmd
发送 prompt(主命令)app/cli/cmd/tell.gotellCmd、doTell
客户端 Tell 调度app/cli/plan_exec/tell.goTellPlan
客户端 build / applyapp/cli/plan_exec/build.go、app/cli/plan_exec/apply_exec.goBuild
Server 入口(拉起 LiteLLM、装路由、起服务)app/server/main.gomain、model.EnsureLiteLLM
路由表(URL→handler)app/server/routes/routes.goaddApiRoutes、addProxyableApiRoutes
tell / build 流式路由app/server/routes/routes.go:162-163TellPlanHandler、BuildPlanHandler
服务端 tell handlerapp/server/handlers/plans_exec.goTellPlanHandler
规划 / 构建核心目录app/server/model/plan/tell_*.go、build_*.go
竞速构建app/server/model/plan/build_race.gobuildRace
结构化编辑(tree-sitter)app/server/syntax/structured_edits_tree_sitter.goExecApplyTreeSitter
模型角色定义app/shared/ai_models_roles.goModelRole、AllModelRoles
模型包定义app/shared/ai_models_packs.goDailyDriverSchema、BuiltInModelPacks
共享数据模型app/shared/context.go、data_models.go、plan_result.go
LiteLLM 代理app/server/litellm_proxy.pypassthrough、_oauth_get_hdrs
目录总布局仓库根app/{cli,server,shared}、README.md

本章只做全景与导航,不深入任何单一机制。想看"大脑怎么规划",从 01-tell-loop.md 开始。