1. 项目概述一个为复杂工程任务设计的结构化工作流如果你经常使用命令行工具来处理软件开发任务可能会遇到一个痛点面对一个复杂的需求比如“重构一个模块”或“设计一个新API”思维很容易陷入混乱。你需要在终端、代码编辑器、浏览器和笔记软件之间来回切换思路被打断上下文丢失最终要么草草了事要么半途而废。今天要聊的这个gplasky/gemini-cli-blueprint-extension就是为了解决这个痛点而生的。它不是另一个代码生成器而是一个结构化的工作流引擎直接集成在 Gemini CLI 里帮你把“一团乱麻”的复杂任务梳理成一条清晰、可追踪、可暂停的“生产线”。简单来说这个扩展为 Gemini CLI 增加了一套以/blueprint:开头的命令。它的核心思想是模仿一个资深工程师的思考和工作路径接到任务后先做调研Research然后制定计划Plan接着拆解任务Define再去执行Implement最后验证Test。整个过程的状态比如你的计划草稿、待办清单、执行记录都会被自动保存为 Markdown 文件。这意味着你可以随时按CtrlC中断去开个会、喝杯咖啡回来敲一个/blueprint:resume就能无缝接上完全不用担心“我刚才想到哪了”。我最初接触它是因为要处理一个遗留系统的数据迁移脚本需求模糊依赖复杂。手动操作很容易出错用这个扩展走了一遍PLAN - DEFINE - ACT的循环后不仅脚本一次跑通整个过程产生的PLAN.md和TODO.md还成了绝佳的项目文档。它特别适合独立开发者、技术负责人或者任何需要系统性解决非 trivial 编码任务的工程师。接下来我会带你深入它的设计思路、手把手走一遍完整流程并分享一些我踩过坑才总结出来的实战技巧。2. 核心设计思路为什么是“PLAN - DEFINE - ACT”这个扩展的骨架就是标题里提到的PLAN - DEFINE - ACT循环。这听起来像某种管理学术语但把它应用到软件开发上却出奇地贴合。我们来拆解一下这三个阶段分别对应什么以及为什么这种设计能提升效率。2.1 PLAN 阶段从模糊需求到清晰路线图PLAN阶段的核心命令是/blueprint:plan。它的输入是一个模糊的目标比如“为我们的用户模型添加一个基于角色的权限系统”。它的输出是一个结构化的PLAN.md文件。这个文件不是随便几句描述而是一个包含背景分析、目标定义、约束条件、技术选型建议和分阶段步骤的详细方案。为什么这步至关重要我见过太多项目一上来就mkdir src然后开始狂写代码写到一半发现架构有问题或者漏掉了关键的非功能需求。/blueprint:plan强制你进行“前置设计”。它会引导 Gemini 去思考现有的代码结构是什么有哪些依赖安全性、性能、可维护性方面需要考虑什么最终生成的计划会像一个经验丰富的技术方案让你在动手前就看到全貌和潜在风险。注意很多人会觉得“让AI写计划”不靠谱。这里的要点是你要把/blueprint:plan看作一个高级别的技术搭档而不是一个听话的秘书。你需要用清晰、无歧义的自然语言描述目标并积极审查它生成的计划。如果它理解有偏差你应该立即用/blueprint:refine去修正计划而不是将错就错地进入下一阶段。2.2 DEFINE 阶段将宏观计划拆解为可执行任务有了一个可靠的PLAN.md下一步就是/blueprint:define。这个命令的作用是把计划中“分阶段步骤”那样的宏观描述转化为一个具体的、可操作的、线性或并行的任务列表也就是TODO.md。例如计划里可能有一项是“实现数据访问层”。/blueprint:define会把它拆成“1. 在src/dal/目录下创建user_repository.py2. 定义User实体类3. 实现基础的 CRUD 方法4. 编写单元测试桩”。每一个任务都应该是原子性的有明确的完成标准。这个阶段的价值在于降低认知负荷。面对一个庞大的计划人容易感到无从下手或焦虑。而一个清晰的TODO.md就像游戏的任务列表你只需要专注于“下一个任务是什么”。这种“任务驱动”的开发模式能极大提升心流状态和完成效率。2.3 ACT 阶段在安全护栏下的自动化执行ACT阶段是工作流的执行引擎主要包括/blueprint:implement和/blueprint:test。这是整个扩展最体现“人机协作”智慧的地方。关键特性用户批准制User Approval。当运行/blueprint:implement时Gemini 不会闷头把TODO.md里的任务全部执行完。相反对于每一个任务尤其是涉及文件创建、修改、删除的它都会先分析当前代码上下文。提出它将要做的具体更改例如展示一个diff对比。停下来等待你的批准y或拒绝n。这个设计我称之为“安全护栏”。它防止了AI因误解而破坏现有代码给了你最终的控制权和审查机会。你可以把它想象成一个非常主动且高效的“结对编程”伙伴它负责起草代码你负责审核和决策。/blueprint:test命令则是在实现后自动根据PLAN.md中的验收标准或项目现有的测试框架去验证实现是否正确。如果测试失败你可以自然地使用/blueprint:refine命令将问题反馈回去工作流会引导你回到PLAN或DEFINE阶段进行修正形成一个闭环。3. 安装、配置与核心命令详解了解了核心思想后我们来看看怎么把它用起来。安装过程非常简单但有一些配置细节和命令的灵活用法能让你用得更顺手。3.1 安装与环境准备首先你需要已经安装并配置好Gemini CLI。这是使用此扩展的前提。安装扩展只需要一行命令gemini extensions install https://github.com/gplasky/gemini-cli-blueprint-extension.git --auto-update我强烈建议加上--auto-update参数。这个扩展还在积极迭代中作者会修复问题并添加新功能自动更新能让你始终用到最新最好的版本。安装成功后你可以通过gemini extensions list来确认blueprint扩展已在列表中。管理命令也很直观gemini extensions update blueprint手动更新。gemini extensions uninstall blueprint卸载。安装本身没有复杂的配置但有一个隐藏的实用技巧这个扩展的所有状态文件PLAN.md,TODO.md,ACT.md默认都生成在你运行命令时的当前工作目录。所以最佳实践是为每一个独立的项目或任务创建一个单独的目录。比如mkdir ~/projects/auth-system-overhaul cd ~/projects/auth-system-overhaul然后在这里运行/blueprint:plan。这样能保证工作流的上下文隔离非常清晰。3.2 八大核心命令实战解析扩展提供了8个命令可以分为“主工作流命令”和“辅助工具命令”两类。主工作流命令/blueprint:research 主题这是可选的第一步。当你对一个领域完全陌生时先用它进行信息搜集。比如/blueprint:research “如何在Go中高效处理JSON序列化”。它会整理出关键概念、流行库和最佳实践为后续制定计划提供弹药。/blueprint:plan 目标工作流的正式起点。目标的描述至关重要。好的描述应该是“目标导向”且“上下文丰富”的。反面例子“优化代码”太模糊。正面例子“重构项目根目录下的data_processor.py文件将其中超过300行的process()函数按单一职责原则拆分为数据加载、清洗、转换、输出四个独立类并确保现有单元测试全部通过。”执行后当前目录下会生成PLAN.md务必仔细阅读并确认。/blueprint:define此命令不需要参数。它直接读取当前目录下的PLAN.md文件并生成TODO.md。如果PLAN.md不存在它会提示你。生成后打开TODO.md检查任务拆解是否合理粒度是否合适。/blueprint:implement核心执行命令。它读取TODO.md并开始逐个任务执行。如前所述每个可能改变系统的操作都会请求批准。你可以全程监控也可以批量批准几个低风险任务。/blueprint:test验证命令。它会尝试运行相关的测试。具体行为取决于项目如果项目有pytest/jest等它会尝试运行相关测试套件。如果没有它会基于PLAN.md中的要求生成一些验证性代码或检查点。 测试失败是常态这正是迭代循环的开始。/blueprint:refine 反馈最重要的迭代命令。当测试失败或你对任何阶段计划、任务、代码不满意时使用它。例如/blueprint:refine “单元测试在内存数据库连接环节失败请检查TODO.md中是否遗漏了测试环境的初始化任务并修正实现代码。”这个命令能智能地将你带回正确的阶段进行修正。辅助工具命令/blueprint:resume“时光机”命令。无论你因为什么原因中断了工作流关闭终端、重启电脑只要回到项目目录运行这个命令它就会自动读取已有的状态文件PLAN.md,TODO.md,ACT.md判断你进行到哪一步并提示你接下来该运行哪个命令如/blueprint:implement或/blueprint:test。这对保持上下文连续性有巨大帮助。/blueprint:clear清理命令。它会删除工作流在当前目录生成的所有状态文件PLAN.md,TODO.md,ACT.md等。当你一个任务彻底完成或者想完全重新开始时使用。使用前请确认这些文件的内容已无保留价值或已备份。4. 完整实战演练从零构建一个简单的CLI工具光说不练假把式。我们用一个实际例子走一遍全流程“创建一个Python CLI工具用于统计指定目录下不同编程语言源代码文件的行数。”4.1 阶段一调研与计划首先我们创建一个专属目录并进入。mkdir line-counter cd line-counter虽然我们对“统计行数”这个需求很明确但为了演示我们先做一点调研了解是否有现成的轮子或最佳实践。/blueprint:research “Python中统计目录文件行数的常用方法、性能考量以及打包为CLI工具的最佳实践”Gemini 会返回一份摘要可能提到os.walk,pathlib, 处理二进制文件忽略注释以及使用argparse或click库构建CLI。这让我们心里更有底。现在开始正式计划。/blueprint:plan 创建一个名为 ‘lcount’ 的Python命令行工具。功能接受一个目录路径作为参数递归遍历该目录识别出.py, .js, .java, .go等常见源代码文件并分别统计每种语言文件的总行数及所有文件的总行数。要求使用argparse解析参数代码结构清晰有基本的错误处理如目录不存在并且可以通过 ‘pip install .’ 方式安装。执行后查看生成的PLAN.md它应该包含目标清晰复述。技术栈Python 3.8argparse,pathlib。项目结构建议lcount/ ├── setup.py ├── lcount/ │ ├── __init__.py │ ├── cli.py # 命令行入口 │ └── counter.py # 核心统计逻辑 └── README.md实施步骤初始化项目结构。编写setup.py。在counter.py中实现文件遍历和行数统计逻辑。在cli.py中实现参数解析和主函数。编写基本的错误处理和用户输出。本地测试安装和功能。验收标准能成功安装对测试目录运行能输出正确统计。审查这个计划如果觉得pathlib比os.walk更现代可以此时用/blueprint:refine “请将实施步骤中关于文件遍历的部分明确指定使用 pathlib 库而非 os.walk。”进行微调。4.2 阶段二任务定义计划确认无误后生成任务列表。/blueprint:define查看生成的TODO.md内容会是类似这样的原子任务Create project root directory structure (lcount/,lcount/lcount/).Createsetup.pywith basic metadata and entry point configuration.Createlcount/__init__.py.ImplementFileCounterclass inlcount/counter.pywith methods to detect file type and count lines.Implement command-line argument parsing inlcount/cli.py.Write the main function incli.pythat integrates the counter and prints results.Add error handling for non-existent directory.Test the tool manually on a sample directory.Create a basicREADME.mdfile.这个列表已经非常可操作了。你可以手动调整任务的顺序或描述。4.3 阶段三执行与测试现在开始自动化执行。/blueprint:implement你会看到Gemini开始工作。例如对于任务1它可能会显示Proposing to create directory ‘lcount/lcount’. Approve? (y/n):输入y批准。对于创建setup.py它会展示文件内容让你确认。对于编写counter.py逻辑它会展示完整的代码。这是一个关键的审查环节你需要检查代码逻辑是否正确比如是否忽略了空行或注释根据需求文件类型判断是否合理。逐项批准直到所有任务完成。然后进行测试。/blueprint:test由于我们还没有写正式的单元测试Gemini可能会执行一些集成测试比如尝试在项目根目录运行pip install -e .然后运行lcount .来统计当前目录。它会报告安装是否成功以及输出是否符合预期。假设测试发现一个问题它把.md文件也当成源代码统计了。这时我们就需要迭代。/blueprint:refine “测试发现工具将 .md 文件也计入了。请修改 counter.py 中的文件类型检测逻辑只统计 .py, .js, .java, .go 这几种明确的后缀。更新完成后重新运行测试。”这个命令会智能地识别到需要修改counter.py属于IMPLEMENT阶段并在修改后重新触发/blueprint:test。4.4 阶段四恢复与清理如果在编写cli.py时你突然需要离开直接关闭终端即可。明天回来进入line-counter目录只需/blueprint:resume它会告诉你“检测到TODO.md存在且ACT.md记录上次执行到任务5。建议继续执行/blueprint:implement。” 你输入命令就能从断点继续。当项目全部完成功能稳定后运行/blueprint:clear所有工作流文件被清除只剩下你最终的项目代码干净利落。5. 高级技巧与避坑指南经过多个项目的实战我总结了一些能让这个扩展威力倍增的技巧以及需要注意的“坑”。5.1 如何写出高质量的“计划”指令这是成功的一半。模糊的指令导致模糊的结果。提供上下文如果任务涉及修改现有项目在运行/blueprint:plan前可以先在聊天区用/code命令提供相关代码文件的片段。这样Gemini生成的计划会更贴合实际。明确约束在指令中直接说明技术栈、性能要求、代码风格如“遵循PEP 8”、“使用async/await”。举例说明对于复杂逻辑可以举例说明输入和期望的输出。例如“…处理后的数据格式应为JSON例如输入{‘a’:1}输出应为{‘a’: 1, ‘squared’: 1}”。5.2 状态文件的管理艺术PLAN.md,TODO.md,ACT.md是宝藏也是需要管理的资产。纳入版本控制强烈建议将这些文件也加入git。它们记录了项目演进的完整思路是极好的文档。在IMPLEMENT阶段Gemini生成的代码diff也可以被git记录。不要跨项目混用切记“一个目录一个工作流”。不要在同一个目录下同时进行两个不相关的blueprint任务状态文件会互相覆盖。手动编辑的时机你可以直接手动编辑TODO.md。比如你觉得某个任务拆得不够细可以自己插入几行。/blueprint:implement会忠实执行你编辑后的列表。PLAN.md也可以手动润色使其更清晰。5.3/blueprint:refine的进阶用法这是最有价值的命令用得好可以形成高效的人机对话循环。精准反馈反馈信息要具体。不要说“代码不对”而要说“在counter.py第23行的count_lines函数中对于多行注释’’’…’’’的处理有误它被计入了行数。请修正逻辑使其能跳过这种多行注释。”指定回溯阶段你可以明确告诉它回到哪一步。例如/blueprint:refine “这个错误是因为计划阶段对并发场景考虑不足。请更新 PLAN.md增加关于线程安全的部分然后重新生成 TODO.md。”处理测试失败当/blueprint:test失败时直接将错误信息复制粘贴到refine指令中AI通常能很好地理解并修复。5.4 常见问题与排查命令未找到确保已正确安装扩展且安装的Gemini CLI版本支持扩展功能。尝试gemini extensions list查看。状态混乱如果工作流状态似乎错乱了比如该有的文件没了最直接的方法是运行/blueprint:clear彻底清理然后从一个清晰的阶段如/blueprint:plan重新开始。必要时可以手动删除那些.md文件。AI生成代码不符合预期这是最常见的“坑”。永远不要盲目批准。仔细阅读它提出的每一个更改。如果代码风格、逻辑或架构与你预期不符果断拒绝n然后使用/blueprint:refine给出非常具体的修改指示。把它当作一个需要明确需求、严格验收的初级开发者。复杂任务一次搞不定对于非常庞大的任务如“重构整个微服务”不要试图用一个/blueprint:plan覆盖所有。将其分解为多个子项目为每个子项目创建独立的目录和独立的工作流。PLAN.md本身就可以成为这个宏观分解的产出。这个扩展的本质是将你从“同时思考战略、战术和操作”的多线程压力中解放出来让你能更专注地在每个阶段进行深度思考和决策。它强迫你遵循一个经过验证的有效流程并用自动化和持久化来保障这个流程的连贯性。对于任何需要严谨、可回溯地完成复杂任务的开发者来说它都是一个能显著提升生产力和代码质量的利器。我开始用它之后最大的感受不是“写代码更快了”而是“做复杂的事情时心里更有底了”。