先说结论用 LLM 构建一个真实可用的工具这件事的入门门槛已经低到一个人可以完成但它没有取消掉开发者最该承担的两件事——定义什么算做完以及验证它到底做对没有。Picodevil 这个项目名初看有点俏皮短、好记还带一点小恶魔的个性。但真正值得写一篇技术文章来拆的是它标题里的后半句using an LLM。这句话背后代表的不只是我用 AI 写了几行代码而是开发方式的迁移——从我亲自写每一行到我定义问题、评审输出、守住边界。这篇文章不会去复述某一条新闻也不会堆一段天花乱坠的AI 取代程序员叙事。我会以 Picodevil 这类用 LLM 从 0 到 1 构建的小项目为切入点讲清楚三件事用 LLM 建项目时真正降低的是哪类成本、哪些成本一分没少一套可复制的从需求到运行的完整流程应该怎么走以及在实际开发里哪些坑是几乎每个人都会踩的。文章最后会给出一个最小可运行的 CLI 工具示例、验证方法和常见问题排查表方便你直接照着做。1. 这篇文章真正想解决的问题很多开发者对用 LLM 建项目的认知是两极化的。一边认为 AI 写代码全是垃圾只能用来生成注释另一边觉得只要把需求往对话框里一贴项目就能自己长出来。真实情况在两者之间而且比两边都更有意思。先说传统方式的时间开销。假设你要做一个自己的小工具比如一个批量处理图片的命令行程序通常的耗时分布是搭工程结构、写样板代码、查三方库文档、处理依赖兼容、写测试、写 README、调格式。真正需要动脑的核心算法往往只占一小部分大量时间消耗在项目和代码之间的胶水上。LLM 真正降低的正是这部分胶水成本。脚手架、配置、重复的 CRUD、API 调用封装、测试骨架、文档初稿这些东西 LLM 生成得又快又完整。但注意另外几项成本它没有降低需求拆解、正确性验证、安全边界、生产环境的问题排查。也就是说LLM 把从 0 到 0.8的过程变得非常快但从 0.8 到 1.0的责任仍然在开发者身上。所以这篇文章最想解决的问题是在一个规模不大、边界清晰、可以快速验证的小项目里怎么用 LLM 把它从一句话需求变成一个真正能跑、能测、能交付的工具。Picodevil 这样的项目就是 LLM 的最佳适用区间——它小到一个人能 hold 住又大到足以暴露出流程里所有的坑。适合读这篇文章的人是想用 LLM 做真实工具的独立开发者、想给团队引入 AI 辅助开发的工程师以及刚开始学 LLM 应用开发、想找一个正确姿势入门的同学。2. Picodevil 是什么先分清用 LLM 写代码和用 LLM 做工程从标题提供的信息看我们能确定的只有两件事作者构建了一个叫 Picodevil 的项目以及这个项目是在 LLM 参与下完成的。至于 Picodevil 具体是命令行工具、网页小应用还是硬件 DIY 项目材料里没有明确信息更稳妥的判断是先不纠结形态把注意力放在用 LLM 构建这件事本身。名字里的 Pic 可能是 picture 的缩写也可能取自 Raspberry Pi Pico 的 Pico或者只是作者喜欢的一个短音节。这在用 LLM 开发时其实是个常见现象项目名往往是个性的、随意的真正决定项目命运的是需求边界和验证标准。在此基础上我建议把用 LLM 建项目分成两种模式它们的工程含义完全不同。模式典型形态人的职责适合场景辅助补全模式自动补全、代码片段、问答自己写主逻辑LLM 提速在已有工程里开发对话式工程模式生成脚手架、整文件、测试、报错分析定义需求、评审代码、验证结果从 0 到 1 的小工具、原型、独立项目Picodevil 这类项目更贴近第二种。这种模式里开发者更像一个技术负责人你描述问题LLM 给出第一版实现你评审、发现问题、指正它再改直到满足验收标准。这个过程和传统的结对编程非常像只不过你的结对对象变成了一个知识面很广但偶尔会自信地说错话的实习生。说到这就必须提几个最近讨论度很高的概念LLM Agent、MCP、RAG、编排框架。它们的本质都在回答同一个问题——怎么把模型的生成能力安全地放进真实工作流。LLM Agent让模型不只是生成文本而是通过工具调用来执行动作比如读文件、跑命令、调 API。它的优点是自主风险也在自主。MCPModel Context Protocol一种把外部工具和数据源标准化接入模型的协议解决了每个模型接一套工具的重复劳动。RAG检索增强生成把外部知识库检索结果拼进提示词让模型基于真实资料回答是对抗幻觉的常用手段。编排框架比如 LangChain、LlamaIndex以及 Java 生态常讲的 Spring AI MCP RAG Agent 组合负责把多步调用组织成稳定流程。对 Picodevil 这种量级的项目我的判断是先不需要为了用框架而用框架。用最朴素的对话 评审 验证闭环把第一个版本跑通当你发现需要稳定的工具调用和多步流程时再引入 Agent 和编排框架那才是它们发挥作用的时候。3. 环境准备与前置条件先想清楚三个选择题动手之前别急着打开 IDE先做三个选择题。它们决定你后面所有步骤的体验。3.1 选模型通道云端 API 还是本地推理做 LLM 应用开发第一条分岔路就是模型跑在哪。对比维度云端 API本地推理成本按 token 计费用多少付多少一次性硬件投入电费成本为主隐私数据要出本地需评估合规性数据不出机器适合敏感场景速度取决于网络和厂商负载取决于显卡和量化配置上下文长度通常较大按模型而定受显存和框架限制维护成本几乎为零要自己维护环境、版本、显存如果只是做学习和个人项目云端 API 往往是性价比最高的选择省去大量环境折腾。如果数据敏感、离线需求强或者纯粹想研究推理系统再考虑本地推理。本地推理常见的有 Ollama、vLLM、llama.cpp 这类工具链版本差异较大使用时以官方文档和实际安装版本为准不要照抄网上的旧命令。3.2 选推理精度FP32、FP16 还是 BF16这个话题最近讨论度很高对大项目影响明显对小工具影响不大。简单理解FP32 是单精度精度高、占显存多FP16 是半精度速度快但数值范围有限BF16 是 Brain 浮点格式和 FP16 一样占 16 位但保留了更大的指数范围训练场景更稳。推理时常见做法是用 FP16 或 BF16 减少显存占用、提升吞吐。对小项目来说直接用框架默认值就行不必在精度上过度纠结。3.3 选工具链我建议的最小环境如下版本请以实际项目为准Python 3.10 或更高版本。Git用于版本控制。VS Code 或你习惯的 IDE配合官方 AI 插件或使用 Cursor 这类深度集成 LLM 的编辑器。虚拟环境管理推荐 venv 或 uv。环境变量的管理从第一天就要规范。新建一个.env.example作为模板真正带密钥的.env永远不要进版本库。# 文件路径.env.example # 复制为 .env 后按需填写不要把真实密钥提交到版本库 LLM_API_KEY LLM_BASE_URLhttps://api.example.com/v1 LLM_MODELyour-model-name.gitignore 也要第一时间建好# 文件路径.gitignore .env .venv/ __pycache__/ *.pyc dist/如果你是本地推理路线先确认模型能跑起来再开始项目ollama pull qwen2.5:7b ollama run qwen2.5:7b注意模型名和版本会随生态更新而变化命令只是示意。跑通了再进入下一步。4. 核心流程拆解从一句话到可运行项目用 LLM 建项目的流程可以收敛成六步。这六步不是我的发明而是从大量AI 辅助开发翻车/成功的案例里提炼出来的共性。4.1 定义完成的标准无数项目翻车不是因为 LLM 代码写得差而是因为需求本身模糊。不要说写一个处理图片的工具要说输入一个目录把里面所有 jpg/png/webp 图片等比缩放到最大宽度 800 像素输出到 dist 目录目录不存在就自动创建空目录时给出友好提示。定义完成标准最好的办法是写验收清单有哪些输入、哪些输出、边界情况怎么处理。这张清单既是给 LLM 的需求说明也是你最后验证的依据。4.2 拆里程碑把项目拆成小块脚手架 → 核心函数 → CLI 入口 → 测试 → 文档 → 打包。每个里程碑都要能独立验证。这一步的目的是把一个大 prompt 生成三千行代码的风险拆散避免一次性引入大量无法定位的错误。4.3 让 LLM 生成脚手架把需求、技术栈、目录结构、验收标准写进一个结构化提示词要求 LLM 先讲思路再给代码。一个可复用的提示词模板长这样项目背景我需要用 Python 写一个命令行小工具名叫 picodevil-demo。 功能要求 1. 遍历 input_dir 下的 jpg/png/webp 图片 2. 等比缩放到 max_width 像素宽 3. 输出到 output_dir 4. 提供命令行参数带默认值。 非功能要求 1. 代码结构清晰入口在 picodevil_demo/main.py 2. 使用 typer 和 Pillow 3. 包含 pytest 测试 4. 先列出你会怎么做再给出代码不要只贴代码。 接受标准python -m pytest 全绿CLI 能处理空目录并给出友好报错。注意最后一条先列出做法再给代码。这一步能逼着 LLM 暴露它的设计思路也逼着你提前看到潜在问题。4.4 逐文件评审与修改LLM 生成的代码一定要读。你不是在找语法错误而是在找设计问题路径处理是否安全、异常分支是否完整、依赖版本是否合理。这个环节最忌讳看着能跑就合进去。4.5 用测试和命令验证跑测试、跑 CLI、看输出。验证时不要只验证 happy path还要验证边界空目录、不存在目录、超大图片、无读写权限。边界测试往往能暴露 LLM 代码里最隐蔽的假设。4.6 把报错喂回给 LLM这一步是效率倍增器。运行失败时把完整报错贴给 LLM附上相关代码片段它会比你自己从头查更快定位。但同样要带着判断力——它给出的修复不一定对验证一遍才算数。5. 完整示例用 LLM 构建一个最小 CLI 工具为了演示完整流程我以picodevil-demo为名构建一个最小 CLI 工具批量缩放图片。这个示例刻意保持简单方便你把注意力放在流程而不是某个库的细节上。文件结构picodevil-demo/ ├── pyproject.toml ├── .gitignore ├── .env.example ├── picodevil_demo/ │ └── main.py └── tests/ └── test_main.py第一个文件是项目配置# 文件路径pyproject.toml [project] name picodevil-demo version 0.1.0 description A minimal CLI tool demo built with LLM assistance requires-python 3.10 dependencies [ typer0.12,1.0, Pillow10.0,12.0, ] [project.optional-dependencies] dev [ pytest8.0,9.0, ] [project.scripts] picodevil-demo picodevil_demo.main:app核心代码放在picodevil_demo/main.py# 文件路径picodevil_demo/main.py 把指定目录下的图片统一缩放到最大宽度并输出到 dist 目录。 from pathlib import Path import typer from PIL import Image app typer.Typer(helpPicodevil demo: 批量处理图片的小工具) def resize_image(src: Path, dst: Path, max_width: int) - None: with Image.open(src) as img: ratio max_width / img.width new_height max(1, round(img.height * ratio)) resized img.resize((max_width, new_height), Image.Resampling.LANCZOS) resized.save(dst) app.command() def main( input_dir: Path typer.Argument(..., existsTrue, file_okayFalse), max_width: int typer.Option(800, min1), output_dir: Path typer.Option(Path(dist)), ): 将 input_dir 下的图片jpg/png/webp等比缩放到 max_width 像素宽。 output_dir.mkdir(parentsTrue, exist_okTrue) supported {.jpg, .jpeg, .png, .webp} for src in sorted(input_dir.iterdir()): if src.suffix.lower() not in supported: continue dst output_dir / f{src.stem}_w{max_width}{src.suffix.lower()} resize_image(src, dst, max_width) typer.echo(fprocessed: {src.name} - {dst.name}) if __name__ __main__: app()这里有一个非常典型的 LLM 生成代码的坑老版本 Pillow 里常见的Image.ANTIALIAS写法在较新版本中已经被移除如果你让 LLM 按网上旧代码生成它很可能给你一个运行时报错的版本。正确做法是用Image.Resampling.LANCZOS这也是评审环节最容易发现的问题类型——不读文档、不跑测试仅靠看着对就提交很容易踩中。测试文件tests/test_main.py# 文件路径tests/test_main.py from pathlib import Path from PIL import Image from picodevil_demo.main import resize_image def test_resize_image_keeps_ratio(tmp_path: Path) - None: src tmp_path / demo.png dst tmp_path / demo_out.png with Image.new(RGB, (1600, 800), blue) as img: img.save(src) resize_image(src, dst, max_width800) with Image.open(dst) as out: assert out.width 800 assert out.height 400测试只验证了一个核心不变量缩放后宽高比保持不变。这个测试是 LLM 生成的但它符合工程直觉——不验证具体像素颜色只验证比例关系。反过来如果 LLM 生成的测试全是调用不报错级别的空测试那就要提高警惕说明它只是在凑覆盖率。安装依赖python -m venv .venv source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1 pip install -e .[dev]准备两张测试图片后运行mkdir -p samples picodevil-demo samples --max-width 800 --output-dir dist pytest -q到这里一个最小可运行的 LLM 构建项目就完整跑通了。整个过程的核心不是命令多高级而是每一步都有明确的验证点依赖装得上、CLI 跑得动、测试有断言。6. 运行结果与效果验证运行上面的命令后预期输出类似processed: photo1.jpg - photo1_w800.jpg processed: photo2.png - photo2_w800.png如何判断成功CLI 正常退出退出码为 0。dist 目录出现缩略图且图片宽度等于你传入的 max_width。pytest 全部通过。如果失败第一步不是改代码而是按顺序看三个地方依赖是否装成功。Pillow 在某些精简系统上安装失败很常见看 pip 输出的错误日志。Python 版本是否满足 pyproject.toml 的要求。有些语法或库行为在不同版本下表现不一致。报错发生在哪个阶段。如果是导入阶段报错多半是依赖问题如果是运行阶段报错多半是边界情况没处理。这个排查顺序看起来简单但能过滤掉很大一部分看似复杂的问题。我在实践中见过太多人拿到报错后第一反应是重写整个函数而实际上只是虚拟环境没激活。7. 常见问题与排查思路以下表格汇总了用 LLM 构建项目时最高频的几类问题按出现概率排序。问题现象可能原因排查方式解决方案LLM 生成了不存在的 API 或类模型幻觉把旧版本或想象中的接口当成真的对照官方文档或 IDE 的类型提示核对把报错信息喂回给 LLM 修正或手动改成文档确认过的写法代码能跑但结果不对验证不足LLM 对需求的假设有偏差补充边界测试逐段核对核心逻辑细化验收清单要求 LLM 先解释设计再改代码依赖版本冲突不同库对同一个传递依赖要求不一致pip freeze 查看实际安装版本或使用 uv 生成锁定文件固定版本号在 pyproject.toml 中明确上下界上下文太长被截断对话历史超过模型上下文窗口检查是否有超长文件反复粘贴拆文件、只贴相关片段或引入 RAG 方式检索项目文档API Key 泄漏到仓库把密钥写进代码或配置文件后提交git log 检查历史查找是否包含密钥立即轮换密钥改用环境变量用 secret 扫描工具检查历史本地模型输出不稳定模型太小、精度配置不当或上下文不足对比不同模型在相同任务上的输出换更大模型或改用云端 API必要时调整 FP16/BF16 等推理配置路径穿越或输入校验缺失LLM 生成的代码直接信任用户输入检查所有文件路径和处理外部输入的位置加白名单、路径规范化校验遵守最小权限原则测试全过但生产环境失败测试数据与真实数据差异大用真实样本跑集成验证增加集成测试在 staging 环境验证后再发布RAG 场景向量 API 未配置检索模块依赖的向量服务没有正确接入查看启动日志和向量 API 配置项按官方文档补全向量 API 配置先跑通单个检索用例这些问题的共同点是它们都不会被代码能运行这一条标准拦住。用 LLM 构建项目时真正的风险不在生成阶段而在验证阶段。8. 最佳实践与工程建议如果把这套流程用在真实项目里下面这些工程建议值得当作默认规范。8.1 小步提交每次都留回滚点LLM 生成代码的速度远快于你的评审速度这会让一次性改动过大成为最大的隐性风险。建议每次只让 LLM 完成一个小里程碑测试通过后立即提交 Git。生产环境变更前先备份、确认回滚方案再执行。这不是保守而是对未知代码的基本尊重。8.2 把项目约束写进文件很多团队会让 LLM 读一个类似 AGENTS.md 或 CLAUDE.md 的项目说明文件里面写清楚技术栈、目录规范、禁用项、验收标准。这个做法本质上是把需求上下文持久化避免每次对话都要重新描述一遍。你也可以为自己的项目建一个这样的文件让 LLM 每次开工前先读它。8.3 安全边界必须人工把关LLM 很容易生成看起来功能完整但安全上漏洞百出的代码。尤其是 Agent 场景当模型被允许调用工具时要警惕过度授权问题——只给它完成任务所需的最小工具集不要轻易放开执行任意命令这类权限。API 密钥遵循最小权限原则不要给一个只读任务配上能删库的 key。所有涉及权限、认证、数据库变更的操作必须在授权范围内先在测试环境验证再谈生产。8.4 不要为了框架而框架最近热门的组合是 Spring AI MCP RAG Agent它确实解决了企业级 LLM 应用的编排问题。但对一个命令行小工具来说引入整套框架只会徒增复杂度。判断标准很简单如果几千行业务代码里只有屈指可数的几处 LLM 调用那就用最直接的 API 调用当你要管理多步工具调用、错误重试、知识库检索时编排框架的价值才开始显现。8.5 让 LLM 写测试但不只写测试LLM 生成测试骨架非常高效但它生成的测试往往和它生成的实现共享同一套错误假设。比如实现里判断条件写反了测试可能也跟着写反结果全绿但功能全错。破解办法是测试断言要来自需求验收清单而不是来自实现代码。8.6 文档和注释要人审LLM 生成的 README 通常结构漂亮但偶尔会包含不存在的命令、错误的版本说明。发布前把每个命令实际跑一遍文档里写的每一条都验证一下。这既是文档质量的保证也是你对自己项目的二次 review。9. 总结与后续学习方向回到开头的判断Picodevil 这类项目的意义不在于它用了多先进的模型而在于它示范了 LLM 时代一个独立开发者可以怎样组织工作——把定义问题、评审输出、守住边界这三件事掌握在自己手里把其余重复劳动交给模型。用 LLM 构建工具真正考验的不是提问技巧而是你能不能把完成定义得足够清楚并且有办法验证它。如果你想继续深入建议按这个顺序推进先用本文的六步流程独立完成一个小工具跑通全流程然后尝试给工具加一个 RAG 检索能力感受上下文补充对输出质量的影响再尝试接入 MCP 或 Agent 编排理解工具调用与自主执行的边界最后研究 FP16、BF16、FP32 等推理精度对显存和速度的影响以及本地推理与云端 API 在真实场景下的取舍。这篇内容建议收藏备用。下次当你准备说让 AI 直接帮我写个项目的时候不妨先停下来把需求描述成验收清单——你会发现这个动作本身就是你和 LLM 协作里最有价值的一步。