企业官网建设流程全解析

Plandex REPL 交互式命令行指南：从启动到高效使用

【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex

Plandex 是一个面向大型项目和真实世界任务的 AI 编码代理。它提供了两种交互方式：一种是标准的单命令 CLI 调用，另一种是本文要深入讲解的Plandex REPL（Read-Eval-Print Loop）——一个开发者友好的交互式聊天界面，也是官方文档中明确标注的"最容易上手的 Plandex 使用方式"。本文将围绕 docs/docs/repl.md 展开，结合仓库源码，带你完整掌握 REPL 的启动方式、内置命令、模式切换、启动参数，以及这些功能在 app/cli/cmd/repl.go 等源码中的具体实现。

读完本文，你将能够：在任何项目目录下一键进入 REPL；熟练使用\命令体系、@文件加载、多行模式等核心操作；理解 chat / tell / multi 三种状态机的工作原理；并掌握通过启动 flags 一次性配置模式、自主程度（autonomy）和模型包组合的最佳实践。

一、什么是 Plandex REPL

Plandex REPL 是一个驻留在终端中的交互式聊天与任务执行界面。与一次执行一个命令的 CLI 不同，REPL 让你在同一个会话中持续地对话、加载上下文、查看 diff、应用修改，形成一个完整的"思考-实现-验证"循环。

从源码结构看，REPL 的完整实现由三个关键文件构成：

• app/cli/cmd/repl.go：REPL 命令的入口与核心执行逻辑，包括启动流程、命令解析、补全逻辑；
• app/cli/lib/repl.go：REPL 状态管理（模式、多行开关、历史记录）与子命令执行工具ExecPlandexCommand；
• app/cli/term/help.go：REPL 内可用命令的注册表CliCommands，声明了每个命令在 REPL 中是否可用及其别名。

其中 app/cli/lib/repl.go 定义了 REPL 的核心状态机：

type ReplMode string const ( ReplModeTell ReplMode = "tell" ReplModeChat ReplMode = "chat" ) type ReplState struct { Mode ReplMode IsMulti bool }

可见 REPL 的核心是"双模式 + 多行开关"：Mode决定当前输入是"聊天"还是"执行任务"，IsMulti决定回车键是发送还是换行。这个状态会在会话之间持久化（写入repl_settings目录下的 JSON 文件），因此你上次退出时的模式会保留到下次启动。

二、启动 REPL

2.1 最简启动

在任何项目目录（或子目录）下直接运行：

plandex # 或简写 pdx

从 app/cli/cmd/root.go 的Execute函数可以看到，无参数运行plandex时会被自动路由到 REPL：

// if no arguments were passed, start the repl if len(os.Args) == 1 || ... { replCmd.ParseFlags(os.Args[1:]) replCmd.Run(replCmd, []string{}) return }

也就是说，"启动 REPL"并不需要显式的repl子命令——只要不带命令参数直接运行二进制，就会进入 REPL；当然你也可以显式地执行plandex repl。

2.2 启动时自动创建/复用计划

启动后，REPL 会检查当前目录是否存在 current plan（当前计划）：

• 没有 current plan：REPL 会自动调用new子命令创建一个新计划，并把你在启动 flags 中指定的自主级别与模型包透传给new（见 app/cli/cmd/repl.go）；
• 已有 current plan：直接加载并进入该计划的会话上下文。

因此，你可以在任意子目录中随时进入 REPL 开始工作，无需手动plandex new。

三、REPL 中的命令体系

3.1 所有 CLI 命令在 REPL 内可用

REPL 内输入以反斜杠\开头的命令即可调用全部 Plandex CLI 命令。例如：

\load src/utils.go # 加载文件到上下文 \diff # 查看待应用改动 \apply # 应用改动 \continue # 继续当前计划 \set-auto full # 设置自主级别

CliCommands注册表（app/cli/term/help.go）中标记了Repl: true的命令都会在 REPL 中启用，并带有各自的别名，例如：

在 app/cli/cmd/repl.go 的executor中，\之后的字符串会被解析成命令，通过ExecPlandexCommandWithParams以"子进程方式"执行（详见下文"命令执行的实现原理"），执行完毕后 prompt 会恢复，继续接受下一条输入。

3.2 REPL 专属命令

除了透传的 CLI 命令，REPL 还内置了 7 个专属命令（app/cli/cmd/repl.go 的execWithInput中实现）：

从源码 app/cli/lib/repl.go 可以看到这些别名统一定义在ReplCmdAliases中：

var ReplCmdAliases = map[string]string{ "chat": "ch", "tell": "t", "multi": "m", "quit": "q", "help": "h", "run": "r", "send": "s", }

3.3 多行模式（\multi）

单行模式下，回车即发送 prompt。要输入带换行的长 prompt（例如多段需求说明），输入\multi或\m进入多行模式：

• 回车 → 插入换行；
• \send或\s→ 将多行内容作为一条完整 prompt 发送。

源码中\send的处理会剥离命令本身并把剩余的多行文本作为 prompt（app/cli/cmd/repl.go），若没有可发送的内容会提示No prompt to send。

3.4 用@加载文件到上下文

在 prompt 中输入@加相对文件路径即可把文件载入上下文，例如：

请参考 @src/utils.go 和 @docs/api.md 重构这段逻辑

其实现逻辑位于 app/cli/cmd/repl.go：@后面的路径会被收集并转换成\load <paths> -r命令执行，执行后 prompt 中@之前已输入的文字会被保留回填到输入框中，方便你继续补充 prompt。支持同时引用多个文件，并且会自动补全@路径。

四、两种工作模式：chat 与 tell

Plandex REPL 的核心设计是对话（chat）与实现（tell）分离：

• chat 模式（💬）：与 AI 自由对话、分析问题、讨论方案，不产生任何代码改动；
• tell 模式（⚡️）：描述编码任务，让 Plandex 真正去实现——写代码、构建文件、产生待应用的改动。

在 prompt 输入框前的提示符中，chat 模式显示 💬，tell 模式显示 ⚡️（若同时开启了 auto-apply 与 auto-exec 会额外显示 ❗️ 提醒，见 app/cli/cmd/repl.go）。可以通过\chat/\ch和\tell/\t随时切换，模式会持久化到下次会话。

一个值得注意的交互细节：在 chat 模式下如果 AI 的回复中表达了"切换到实现/编码"的意图，REPL 会检测输出并询问你是否切换到 tell 模式开始实现，确认后可直接"基于当前对话开始实现"（tell --from-chat），形成"先聊方案、确认后落地"的流畅工作流（app/cli/cmd/repl.go）。

五、REPL 启动 Flags：一次配置模式、自主级别与模型包

REPL 支持在启动时通过 flags 预设模式、自主级别和模型包，无需进入后再手动设置。这些 flags 定义在 app/cli/cmd/plan_start_helpers.go 的AddNewPlanFlags中，repl命令在初始化时通过AddNewPlanFlags(replCmd)挂载（app/cli/cmd/repl.go）。

5.1 模式 Flags

--chat, -c Start in chat mode (for conversation without making changes) --tell, -t Start in tell mode (for implementation)

注意：--chat与--tell互斥，同时指定会报错Cannot specify both --chat and --tell flags（app/cli/cmd/repl.go）。

5.2 自主级别（Autonomy）Flags

Plandex 将自主程度划分为 5 个级别，从"完全手动"到"全自动"：

--no-auto None → step-by-step, no automation --basic Basic → auto-continue plans, no other automation --plus Plus → auto-update context, smart context, auto-commit changes --semi Semi-Auto → auto-load context --full Full-Auto → auto-apply, auto-exec, auto-debug

它们与set-auto命令控制的配置一一对应，启动时传入后若当前目录没有 current plan，会被透传给new命令以创建带对应自主级别的计划。

5.3 模型包（Model Pack）Flags

--daily Daily driver pack (default models, balanced capability, cost, and speed) --strong Strong pack (more capable models, higher cost and slower) --cheap Cheap pack (less capable models, lower cost and faster) --oss Open source pack (open source models) --gemini-planner Gemini pack (Gemini 2.5 Pro for planning, default models for other roles) --o3-planner OpenAI o3-medium for planning, default models for other roles --r1-planner DeepSeek R1 for planning, default models for other roles --perplexity-planner Perplexity for planning, default models for other roles --opus-planner Anthropic Opus 4 for planning, default models for other roles

在 app/cli/cmd/repl.go 中，这些 flags 会被按优先级（--no-auto→--full、--oss→--opus-planner等）收集并透传给new命令。此外源码中还有一个 REPL 帮助里也列出但官方 repl.md 中未提及的--reasoning（Reasoning pack），可作为补充了解。

5.4 组合示例

# 以 tell 模式 + 全自动 + 强模型包启动 plandex --tell --full --strong # 以 chat 模式 + 半自动 + 每日驱动模型启动 pdx -c --semi --daily # 以 tell 模式 + 手动逐步确认 + 开源模型启动 plandex -t --no-auto --oss

建议组合：初次使用时建议--no-auto或默认级别，逐步熟悉\apply、\reject、\diff等操作；对模型质量和成本有明确需求时再组合模型包 flags。

六、REPL 的底层实现原理

6.1 子进程执行模型：为什么 REPL 不会崩溃

REPL 执行命令的核心是 app/cli/lib/repl.go 的ExecPlandexCommand：它重新启动同一个二进制（exec.Command(os.Args[0], args...)），把标准输入输出直接连接到当前终端，并通过临时文件捕获命令输出。

这样做有两个关键收益：

1. 隔离性：子进程中的任何os.Exit都不会杀死 REPL 主进程，命令失败后 prompt 依然存活；
2. 信号安全：REPL 忽略 SIGINT，并将中断/终止信号转发给子进程组（app/cli/lib/repl.go），因此你在 REPL 内执行命令时按 Ctrl+C 只会中断子命令。

REPL 还会通过环境变量向子进程传递终端信息（列宽、深/浅色背景、流式前景色、跳过升级检查等），确保子命令的渲染与 REPL 一致（app/cli/lib/repl.go）。

6.2 状态持久化：模式与历史记录

REPL 的模式与输入历史被序列化为 JSON，存放在~/.plandex/repl_settings/<projectId>.json（app/cli/lib/repl.go）。每次执行输入都会调用WriteHistory追加记录（app/cli/cmd/repl.go），\multi、\chat、\tell等切换操作都会调用WriteState持久化当前状态——这也是为什么你退出后重新进入，模式和提示符状态还能保持一致。

6.3 智能补全与容错

REPL 的补全器（app/cli/cmd/repl.go）支持：

• 命令模糊补全：输入\前缀后，基于模糊匹配（fuzzy matching）和前缀匹配给出命令建议，并把内置命令（\chat、\tell、\multi、\quit等）排在前面；
• 路径补全：对@和\load提供项目内活动路径建议（目录会附加/）；
• 嵌套命令补全：\load <dir> -r、\load <dir> --map、\load <dir> --tree、\run <file.md>等上下文相关的建议。

容错方面，如果输入了"疑似命令"但缺少反斜杠（如直接输入load、diff），REPL 会弹出"你是不是想输入这些命令？"的选择列表；若命令拼写相近（编辑距离阈值内，见 app/cli/cmd/repl.go 的findSimilarCommands），也会给出候选；找不到命令时还会提供"显示可用命令"选项。

七、实战工作流示例

场景一：先讨论方案，再落地实现

# 1. 以 chat 模式启动 plandex -c # 2. 讨论方案（纯对话，不产生改动） 💬 我的服务端 API 响应时间变慢了，帮我分析一下可能的原因？ # 3. 确认方案后，切换到 tell 模式 \t # 4. 描述任务 ⚡️ 基于刚才讨论的方案，为 /api/users 增加分页和缓存

场景二：加载上下文 + 多行 prompt 一次性实现

# 在 tell 模式下，输入 \multi 进入多行模式 \multi # 粘贴多行需求，末尾用 \send 发送 请重构以下文件的错误处理逻辑： 1. 统一错误类型 2. 增加日志记录 3. 补充单元测试 \send

场景三：一键带配置启动

# 全自动 + 强模型，直接进入 tell 模式开工 pdx -t --full --strong

八、小结与进一步阅读

Plandex REPL 通过"对话（chat）/ 实现（tell）双模式 + 全量 CLI 命令透传 + 启动 flags 预设配置"的设计，把 AI 编码代理的完整工作流收敛进一个交互式终端界面中。理解其核心命令、模式切换与状态持久化机制，能够显著提升你的日常使用效率。

如果想继续深入了解，可以从以下仓库文件入手：

• app/cli/cmd/repl.go：REPL 入口、命令解析、补全与欢迎界面；
• app/cli/lib/repl.go：状态管理、历史记录与子进程执行模型；
• app/cli/term/help.go：REPL 命令注册表与帮助输出；
• app/cli/cmd/plan_start_helpers.go：启动 flags（自主级别与模型包）定义；
• docs/docs/cli-reference.md：全部 CLI 命令的参考文档。

【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex