1. 项目概述当代码遇上自然语言最近在折腾一些自动化脚本时我总在想有没有一种方式能让写脚本这件事变得像写待办事项清单一样简单比如我想让电脑“把今天下载的图片都压缩一下然后传到网盘备份”如果不用去翻Python的PIL库文档也不用去查curl的命令行参数直接写下这句话就能执行那该多省事。这就是lukechilds/humanscript这个项目吸引我的地方。它的核心目标非常明确让自然语言成为可执行的脚本。简单来说你不再需要严格遵循bash、Python或JavaScript的语法而是用接近日常说话的方式描述任务由它来“翻译”并执行。项目名humanscript直译就是“人类脚本”意图再清晰不过——为人类而非机器设计的脚本语言。它并非要取代传统的编程语言而是在特定场景下提供了一个极具生产力的“快捷方式”。想象一下这些场景你正在给非技术同事写一个简单的数据处理步骤说明你需要快速原型验证一个包含多个步骤的流程或者你只是想用最直观的方式记录并自动化一个重复性任务。在这些情况下纠结于语法细节、导入库、处理异常反而成了负担。humanscript试图抽离这些复杂性让你聚焦于任务逻辑本身。这个项目在Github上由开发者lukechilds维护它本质上是一个解释器。你提供一个用自然语言目前主要是英语写的文本文件.human后缀它就能解析并尝试执行其中的指令。这背后离不开当下大语言模型LLM的能力humanscript巧妙地利用LLM作为“编译器”将模糊的人类指令转化为精确的机器可执行代码。接下来我们就深入拆解一下它是如何工作的以及如何把它用起来。2. 核心原理与架构拆解2.1 设计哲学意图优先于语法传统编程是“语法驱动”的。你必须先知道循环的写法、函数的定义、变量的作用域然后才能用这些“积木”去搭建你的意图。humanscript则反其道而行之是“意图驱动”的。你首先关心的是“要做什么”然后由系统去思考“怎么做”。这种转变带来的最大好处是认知负荷的降低。你不需要在脑海中预先完成从问题域到编程语言语法域的映射。例如你的意图是“给所有新用户发送欢迎邮件”。在传统脚本中你需要1连接数据库2编写SQL查询找出“新用户”3循环结果集4为每个用户调用邮件发送API5处理可能的错误。每一步都涉及具体的库和语法。而在humanscript中你可能只需要描述这个意图它利用LLM的知识来填充这些具体步骤。当然这种便利性并非没有代价。意图的模糊性可能会带来执行结果的不确定性这也是humanscript这类工具需要解决的核心挑战。它的架构正是为了在“人类友好”和“机器精确”之间寻找平衡点。2.2 技术架构LLM作为核心编译器humanscript的架构可以简化为一个三步流水线解析 - 规划 - 执行。第一步解析Parsing当你运行human run your_script.human时humanscript首先会读取整个脚本文件。它并不像传统解释器那样做词法分析和语法分析而是将整段自然语言文本连同当前执行环境的上下文如操作系统、环境变量、工作目录等一起准备成提示词Prompt发送给配置好的大语言模型如OpenAI的GPT系列。第二步规划与生成Planning Generation这是最核心的一步。LLM扮演“高级程序员”的角色。它的任务是根据你的自然语言描述生成一个具体的、可执行的行动计划。这个计划通常是一段代码比如Python脚本。humanscript的提示词工程会引导LLM理解用户的最终目标。将目标分解为一系列具体的、可操作的任务。为每个任务选择最合适的工具或库例如文件操作用os/shutilHTTP请求用requests数据处理用pandas。生成完整、安全、包含适当错误处理的代码。注意生成代码的类型和风格取决于你的配置。默认可能生成Python但你也可以引导它生成Shell脚本或其他语言这体现了其灵活性。第三步执行与反馈Execution Feedback生成代码后humanscript不会直接悄无声息地运行。为了安全和控制它通常会采取以下一种或多种方式显示计划先将LLM生成的代码计划打印出来给你审查询问是否继续执行。这是默认的安全策略。直接执行在确认或信任模式下直接在子进程中运行生成的代码。交互式执行对于需要分步确认或输入的任务可能会在每一步暂停等待用户指令。执行过程中产生的输出标准输出、标准错误会被捕获并呈现给你作为本次任务执行的反馈。如果执行出错错误信息也可能被反馈给LLM用于生成修正方案形成一个简单的调试循环。2.3 与传统脚本及AI助手的区别为了更好地定位humanscript我们可以将其与几种常见工具做个对比特性Humanscript传统脚本 (Bash/Python)Shell AI 助手 (如Warp AI, Fig)纯LLM聊天界面 (如ChatGPT)输入方式自然语言文件 (.human)特定语法代码文件自然语言命令在终端内自然语言对话输出产物动态生成的执行代码 执行结果固定的执行代码单条命令建议文本/代码建议可复用性高。脚本文件可保存、版本管理、重复运行。高。经典的脚本方式。低。通常是单次交互历史命令虽可查但非结构化。中低。对话历史可回顾但需复制代码重新组织。执行控制可预览、确认、自动执行。完全手动编写完全控制执行。建议命令需用户手动确认执行。仅提供建议执行完全脱离聊天环境。复杂度适合中小型、多步骤的流程自动化。适合任意复杂度任务。适合解释命令、生成单条复杂命令。适合开放式问答、代码编写、方案设计。学习成本极低。会用英语描述任务即可。高。需掌握特定语言语法和生态。低。在熟悉终端的基础上增加自然语言交互。低。但需将对话结果转移到执行环境。简而言之humanscript填补了一个细分市场将一次性的、基于对话的AI代码生成变成了可版本化、可重复、可嵌入自动化流程的“脚本”。它比在聊天界面里“复制粘贴”更规范比从头学习一门脚本语言更快捷。3. 环境搭建与快速上手3.1 安装与配置humanscript是一个Node.js工具因此安装的前提是拥有Node.js环境建议版本16。安装过程非常简单通过npm或yarn全局安装即可npm install -g humanscript # 或 yarn global add humanscript安装完成后在终端输入human --version验证是否成功。接下来是最关键的一步配置AI模型后端。humanscript本身不包含模型它需要一个“大脑”。目前它主要支持OpenAI的API这也是最稳定和推荐的方式。获取OpenAI API Key访问OpenAI平台注册并获取你的API密钥。设置环境变量将API密钥设置为环境变量是最佳实践避免硬编码在脚本中。# 在 ~/.bashrc, ~/.zshrc 或终端中直接设置 export OPENAI_API_KEY你的-api-key-here可选配置模型你可以通过环境变量指定使用的模型例如更强大但更贵的gpt-4或者更经济的gpt-3.5-turbo。export OPENAI_MODELgpt-4实操心得模型选择与成本控制对于大多数自动化任务gpt-3.5-turbo已经足够出色且成本低廉。建议初期使用它进行测试和熟悉。只有在任务非常复杂、需要深度推理或对代码质量要求极高时再考虑切换到gpt-4。另外务必在OpenAI后台设置用量提醒防止意外消耗。3.2 编写你的第一个.human脚本让我们从一个最简单的“Hello World”开始但赋予它一点实际意义。创建一个新文件命名为first.human# first.human 向我说“你好世界”并且告诉我当前的日期和时间。是的注释就是用#。脚本内容就是一句平实的描述。保存文件后在终端该文件所在目录执行human run first.human第一次运行时你可能会看到类似下面的输出[Humanscript] 正在分析您的脚本... [Humanscript] 生成的执行计划如下 python import datetime print(你好世界) current_time datetime.datetime.now() print(f当前日期和时间是{current_time})是否执行此计划 (y/N)输入 y 确认后你将看到执行结果你好世界 当前日期和时间是2023-10-27 14:30:15.123456恭喜你已经完成了第一个自然语言脚本。这个过程清晰地展示了 humanscript 的工作流你描述意图 - 它生成具体代码计划- 你确认 - 它执行。 ### 3.3 核心命令详解 human 命令行工具提供了几个核心子命令 * human run file: 运行一个 .human 脚本文件。这是最常用的命令。 * human repl: 进入交互式读取-评估-打印循环REPL模式。你可以像在终端聊天一样一行行地输入自然语言指令并立即执行非常适合快速测试和探索。 bash $ human repl 列出当前目录下所有扩展名为 .txt 的文件 [Humanscript] 生成并执行计划... file1.txt notes.txt 计算 5 的阶乘是多少 [Humanscript] 生成并执行计划... 120 * human --help: 查看所有命令和选项帮助。 一个有用的选项是 --yes 或 -y。在运行脚本时使用会自动对所有确认提示回答“是”这在将 humanscript 嵌入到其他自动化流程中时非常有用。 bash human run my_automation.human -y4. 实战构建一个实用的自动化脚本理解了基础之后我们来看一个更贴近真实需求的例子。假设你是一个内容创作者每周需要处理一批从相机导入的图片任务包括重命名、压缩、备份到云端并生成一个清单。4.1 脚本设计分解复杂任务我们首先将整个工作流用自然语言描述出来保存为weekly_photo_processing.human# weekly_photo_processing.human # 目标处理“~/Downloads/WeeklyPhotos”文件夹中的新图片。 1. 首先检查目录“~/Downloads/WeeklyPhotos”是否存在。如果不存在就打印错误信息并退出。 2. 获取该目录下所有的.JPG和.PNG文件。 3. 如果文件数量是0也打印信息并退出。 4. 为这批文件创建一个新的文件夹路径为“~/ProcessedPhotos/YYYY-MM-DD”使用今天的日期。 5. 遍历每一张图片 a. 将其重命名为“weekly_序号_原文件名”例如weekly_01_IMG_1234.JPG。序号从01开始两位数字。 b. 使用Python的PIL库将图片的宽度调整为1920像素保持长宽比并降低质量为85%进行压缩。 c. 将处理后的图片保存到第4步创建的新文件夹中。 6. 将所有处理后的图片文件名包含路径记录到一个文本文件中命名为“processed_list_YYYY-MM-DD.txt”也放在新文件夹里。 7. 打印本次处理的总图片数量以及新文件夹的路径。 8. 最后询问我是否要将这个新文件夹同步到我的云盘例如Google Drive的某个文件夹。如果我说“是”则调用rclone命令进行同步。这个脚本已经具备了清晰的逻辑结构检查输入、处理文件、记录日志、后续操作。它完全是用人类管理项目的思维写的而不是编程思维。4.2 逐段解析与执行反馈当你运行这个脚本时humanscript会与LLM交互生成一个可能相当长的Python计划。由于步骤较多LLM可能会将任务分解成多个函数或者生成一个包含多个步骤的单一脚本。关键点解析步骤1-3检查与验证LLM生成的代码会使用os.path.exists()和os.listdir()或glob模块来完成。这里体现了自然语言脚本的健壮性考虑——我们在描述中加入了错误处理逻辑。步骤4创建目录LLM会使用os.makedirs(..., exist_okTrue)来创建日期格式的目录。这要求你的描述足够精确“使用今天的日期”。步骤5a重命名这里有一个细节“序号从01开始两位数字”。LLM需要理解这个格式并可能生成使用zfill(2)或f-string格式化的代码来实现weekly_01_...。步骤5b图片处理这是技术核心。LLM需要知道用PILPillow库的Image.open(),resize((width, height)),save(quality85)等方法。如果你的环境没有安装Pillow生成的代码执行时会报错。这时humanscript的优势之一显现出来你可以用自然语言修复它。你可以在REPL里或修改脚本增加一步“在执行前请确保Pillow库已安装如果没有则使用pip安装它。”步骤8交互与外部调用这里展示了humanscript的交互能力。生成的代码可能会使用input()函数等待你的输入并根据输入决定是否调用subprocess.run()来执行rclone sync命令。这连接了自然语言脚本和外部工具链。注意事项文件系统操作的风险任何涉及文件删除、移动、覆盖的操作都需要格外小心。尽管humanscript在生成代码时会被提示考虑安全性但作为使用者最好的实践是始终预览计划在正式运行涉及文件操作的脚本前一定要先看生成的代码计划确认其逻辑是否符合预期。先在小范围或测试目录中运行。在描述中明确“备份”或“保留原文件”。例如说“将图片复制到新文件夹并压缩”而不是“移动”。4.3 进阶技巧上下文与变量简单的脚本是线性的但复杂的任务可能需要记住中间结果。humanscript支持基本的“变量”概念虽然不像编程语言那样严格。你可以在脚本中通过自然语言引用之前步骤的结果。例如获取当前用户的桌面路径并把它称为“桌面路径”。 列出“桌面路径”下所有的PDF文件把结果列表叫做“pdf文件列表”。 如果“pdf文件列表”的数量大于5就打印“你的桌面PDF文件太多了”。LLM在生成代码时会理解“称为”、“叫做”这些词并将对应的结果赋值给一个变量在后续步骤中引用。这极大地增强了脚本的逻辑表达能力。另一个重要概念是系统上下文。humanscript会将一些环境信息自动提供给LLM例如当前操作系统Windows/macOS/Linux当前工作目录环境变量在安全范围内这样当你写“打开我的下载文件夹”时LLM生成的代码就能正确地指向~/Downloads(macOS/Linux) 或C:\Users\用户名\Downloads(Windows)。5. 常见问题、局限性与最佳实践5.1 典型问题排查实录在实际使用中你可能会遇到以下问题问题1执行失败报错ModuleNotFoundError: No module named PIL原因生成的代码依赖了未安装的Python库如Pillow。解决临时解决手动安装所需库pip install Pillow。根本解决修改你的.human脚本在开头或依赖步骤前增加检查。例如“首先确保Python已安装Pillow库。如果没有则自动安装它。” LLM会生成包含try-except导入和subprocess调用pip install的健壮代码。问题2生成的计划看起来不合理或很危险例如要删除所有文件原因你的自然语言描述可能存在歧义或者LLM的理解出现了偏差。解决拒绝执行在预览计划时直接输入n取消。细化描述重新修改脚本使用更精确、无歧义的语言。避免使用“所有”、“清空”等绝对性词汇除非你确实需要。改为“处理source_folder目录下的所有.log文件”。增加安全约束在脚本描述中明确加入约束条件。例如“注意这是一个只读操作不要修改或删除任何原始文件。”问题3脚本运行速度慢原因主要耗时在两部分LLM API调用网络往返模型推理和生成代码的实际执行。解决批量任务对于大量独立任务尽量在一个脚本描述中完成减少API调用次数。不要写10个单独的.human文件去处理10个文件夹。使用本地模型如果支持如果humanscript未来支持或你自行修改其后端连接本地部署的LLM如Llama、Ollama可以极大减少延迟和成本。优化生成代码对于性能关键部分可以在预览生成的计划后手动优化其中的循环或算法然后将优化后的代码固定下来而不是每次都重新生成。5.2 当前局限性认识到工具的边界才能更好地使用它非确定性由于LLM的随机性同一脚本每次运行生成的代码可能略有不同虽然功能应一致但不利于绝对稳定的生产流程。复杂逻辑处理对于需要复杂状态管理、精细错误恢复或高性能算法的任务自然语言描述会变得极其冗长且容易出错不如直接编写传统代码。成本依赖商用LLM API会产生费用。虽然单次调用成本低但高频使用仍需预算。安全性将文件系统、网络等访问权限交给一个根据自然语言生成代码的系统存在潜在风险。必须谨慎对待并预览所有计划。网络依赖必须联网调用API无法在完全离线的环境中使用。5.3 最佳实践总结根据我的使用经验以下几点能让你更安全、高效地利用humanscript从简单到复杂先用它处理一些查询、信息整理、简单文件操作等低风险任务熟悉其工作模式。描述尽可能精确模糊指令产生模糊代码。多用具体路径、具体文件名、具体参数。例如用“将图片宽度调整为1920像素”代替“调整图片大小”。强制预览审阅计划永远不要跳过预览生成的代码这一步。这是保证安全和控制的核心环节。迭代式开发不要指望一口气写一个完美的长脚本。先写主干逻辑运行看效果再逐步添加细节错误处理、日志、确认步骤等。与传统脚本结合humanscript不是“银弹”。将复杂的、稳定的核心逻辑用Python/Bash写好成为模块或函数。然后在.human脚本中用自然语言去“调度”和“组合”这些模块。例如“调用我写好的compress_image.py脚本处理这些图片。”做好版本管理像管理普通代码一样用Git管理你的.human脚本。你可以清晰地看到任务意图的演变过程。humanscript代表了一种有趣的范式转变——编程接口从精确的语法上移到模糊的意图。它最适合的场景是中低频、中等复杂度、流程相对固定的自动化任务尤其是那些你懒得为之专门学习和编写一套完整脚本但又厌倦了手动重复点击的任务。它降低了自动化的门槛让“让电脑自己干活”这个想法变得前所未有的直观。当然它不会让程序员失业而是成为我们工具箱里又一把趁手的“瑞士军刀”用来快速打造原型、编写一次性工具或者仅仅是为了享受用说话来指挥电脑完成工作的那份乐趣。