promptr

用自然语言给代码库动手术：Promptr 深度解析

从改代码到说代码：一个程序员的痛点故事

凌晨两点，你刚写完一个 2000 行的后端模块，突然发现所有函数的命名风格需要从 camelCase 改成 snake_case，或者要在 50 个文件中统一加上统一的错误处理逻辑。这种机械性的重构任务，往往需要几小时手动操作，还要时刻担心漏改、误改。

程序员 Ferris Lucas 也遇到了同样的困境。2023 年初，他决定不再忍受——他用 Node.js 写了一个命令行工具 Promptr，让你直接用自然语言描述想要的修改：把所有函数改成箭头函数、给这个类加上 JSDoc 注释、把这个 Python 脚本改成 TypeScript，然后看 GPT-4 直接在你的文件上动刀。

这就是 Promptr 的核心逻辑：你说做什么，AI 来执行。

工作原理：四步走

第一步：指定文件和提示词。 用户通过命令行传入一个或多个文件路径，以及一段自然语言指令。Promptr 也支持从文件读取提示词（promptr -p my_prompt.txt），甚至从 URL 加载——这意味着团队可以把标准化的 prompt 托管在任何地方。

第二步：读取文件上下文，组装 prompt。 核心在 PromptContext.js 和 FileService.js。FileService 读取所有传入文件的原始内容，PromptContext 将文件名和内容格式化为结构化 context，注入 prompt。默认使用 refactor 模板，将用户 prompt 与文件内容组合后发送给 OpenAI。

第三步：调用 OpenAI API，强制函数调用。 OpenAiGptService.js 是关键，它向 OpenAI 发送请求，并强制开启 function calling——指定一个名为 crud_operations 的函数，参数包含 operations 数组（每项含 crudOperation、filePath、fileContents）。通过 function_call: { "name": "crud_operations" } 强制 GPT 直接输出结构化的文件操作 JSON，而不是随意的自然语言回复。

第四步：解析操作并执行文件变更。 ExtractOperationsService.js 负责解析 GPT 返回的 JSON（内置容错：修复三引号、处理不完整 JSON、正则提取）。RefactorResultProcessor.js 最终将操作列表中的 create/update/delete 指令写入磁盘。

模板系统：LiquidJS 驱动的灵活扩展

Promptr 支持用 LiquidJS 模板引擎预处理 prompt。这带来了一个强大的用例：include 文件（项目级编码规范）。

开发者可以在项目中维护一个 _project.liquid 文件，内容包含项目编码规范。在任意 prompt 中通过 {% render '_project.liquid' %} 引入，Promptr 会先渲染模板，再发送给 GPT。这意味着团队可以为每个项目定制 GPT 的行为约束——这些规范不需要每次手动写，模板自动注入。

内置 4 个模板：refactor（默认）、empty（纯文本对话）、swe（软件工程任务）、test-first（测试先行）。

Token 控制：GPT-3-Encoder 的精确计费

Promptr 使用 gpt-3-encoder 库在本地计算 prompt 的 token 数量。--dry-run 模式下会打印完整 prompt 和 token 计数，用户可以在实际调用 API 前评估费用。这是很有价值的 UX 细节——大文件的 token 消耗可能相当惊人。

架构分析：清晰的服务分层

项目代码约 781KB，结构清晰：

技术栈：Node.js ESM 模块 + Commander.js CLI 框架 + LiquidJS 模板 + OpenAI JS SDK + Mocha 测试框架。

使用限制与风险

Promptr 的本质是让 AI 直接写文件——这意味着：

• 破坏性风险：GPT 的理解偏差可能导致代码损坏（作者建议先 commit 备份，再用 git diff 审查）。
• API 成本：处理大文件时 token 消耗较高，大型代码库需要分批处理。
• 仅支持 OpenAI 模型：不支持 Claude、Gemini 等其他 LLM（basePath 可配置但核心逻辑围绕 OpenAI function calling 设计）。

交互模式也支持管道输入：promptr --model execute < operations.json 允许程序化调用。

适用场景

Promptr 特别适合以下场景：

• 重复性重构：统一命名风格、批量添加类型注解、代码风格规范化
• 快速原型生成：用自然语言描述想要的文件结构，AI 直接生成代码骨架
• 实验性探索：在隔离环境中用不同 prompt 测试 GPT 对同一文件的修改效果

对于希望把 AI 集成到现有开发工作流（而非启动一个 Web UI）的团队，Promptr 是一个轻量且直接的解决方案。