SuperAPI AI 工具集

write-script-bun

编程与开发

查看项目

更新于 10-16 14:51

技能介绍

write-script-bun 是 Windmill 平台(来源为 windmill-labs/windmill-claude-plugin)中的一个技能,用途是指导编写 TypeScript 脚本。以下内容均依据所提供资料整理。

一、用途与运行时选择 该技能明确:在编写 TypeScript 脚本时必须使用它。Bun 是默认且首选的 TypeScript 运行时,拥有完整的 npm 生态与最快的执行速度。除非某个具体用例有重大理由需要使用 Deno,否则任何 TypeScript 脚本都应选择 Bun。

二、脚本结构与通用原则

  • 脚本的输入即其参数。凭据和配置以资源类型(resource-typed)参数传入,绝不硬编码,也不从环境变量读取。
  • 库会自动安装,不要展示安装说明。
  • 在具有入口函数的语言(TypeScript、Python、Go、Rust、PHP、R 等)中,将入口函数命名为 main(C# 中为 Main),并且不要调用它;在 TypeScript 中它必须是 async。SQL、GraphQL、Bash、PowerShell 和 Ansible 脚本没有 main,其参数获取方式由对应语言章节说明。
  • 若语言有 Windmill 客户端(wmill),应使用它与平台交互。

三、TypeScript (Bun) 具体写法 结构上导出一个名为 main 的 async 函数,例如:

export async function main(param1: string, param2: number) { // Your code here return { result: param1, count: param2 }; }

不要调用 main 函数,库会自动安装。 资源类型:凭据和配置存储在资源中并作为参数传给 main,使用 RT 命名空间,例如 export async function main(stripe: RT.Stripe)。使用资源类型前,检查项目根目录的 rt.d.ts 文件以查看所有可用资源类型及其字段;该文件由 wmill resource-type generate-namespace 生成。 导入:如 import Stripe from "stripe"; 与 import { someFunction } from "some-package";。

四、//native 优先 如果脚本只需要 fetch 和 JavaScript 标准库(包括使用 windmill-client 时),优先将其写成 native 脚本:在第一行添加 //native,并使用 write-script-bunnative 技能编写。Native 脚本运行在轻量级 V8 isolate 上,启动更快、可高度并行。windmill-client 可在 native worker 上工作(其调用通过 fetch),因此需要使用 Windmill 客户端并不是避免 //native 的理由。只有当代码(或依赖)需要 Node/Bun 运行时 API(node:* 模块、文件系统、子进程或原生插件)时,才使用常规 bun 语言。

五、Windmill 客户端 通过 import * as wmill from "windmill-client"; 导入。凡与 Windmill 通信(读取资源/变量/状态、运行脚本与流程、S3 对象操作等)都优先使用 windmill-client 而非原始 fetch,它替你处理认证、工作区与基础 URL。fetch 保留给调用非 Windmill 的外部 HTTP API。资料还列出了 windmill-client 的部分 API,如 setClient、getWorkspace、getResource、getRootJobId、runScriptByPath、runScriptByHash、appendToResultStream、streamResult、runFlow、waitJob、getResult、getResultMaybe、cancelJob 等。若要了解谁在运行脚本,读取上下文变量 process.env.WM_END_USER_EMAIL || process.env.WM_EMAIL,WM_USERNAME 为对应用户名。对于未覆盖的端点,可从 windmill-client 导入生成的服务类(JobService、ScriptService 等)。

六、返回值 脚本可返回任意 JSON 可序列化的值;SQL 脚本返回其查询产生的行。返回值可通过 results.step_id 供后续流程步骤使用。

七、预处理脚本(Preprocessor Scripts) 预处理脚本用于在处理来自各类来源(webhook、自定义 HTTP 路由、SQS、WebSocket、Kafka、NATS、MQTT、AMQP、Postgres、GCP Pub/Sub、Azure 或 email)的原始触发数据,再传给流程之前对其进行处理,从而将触发逻辑与流程逻辑分离,并保持自动生成的 UI 整洁。预处理脚本用 TypeScript 或 Python 编写,函数名为 preprocessor 而非 main,接收一个名为 event 的参数。其返回对象决定传给流程的参数值。例如 { b: 1, a: 2 } 会在流程具有名为 a 和 b 的两个输入时,以 a = 2、b = 1 调用流程。

八、CLI 命令与意图区分

  • wmill script preview <script_path>:迭代本地脚本时的默认命令,运行本地文件而不部署。
  • wmill script run <path>:运行已部署到工作区的脚本。仅在用户明确要测试已部署版本时使用,而非本地修改。
  • wmill generate-metadata:为改动的脚本重新生成本地 .script.yaml(输入 schema)和 .lock(解析后的依赖),并刷新 wmill-lock.yaml 中的内容哈希。仅写本地文件,不是部署。
  • 部署本地改动:通过 git push 或 wmill sync push(取决于仓库接线方式)。仅当用户明确要求部署/发布/推送时执行,而非在用户说“运行”“试试”“测试”时执行。 如果用户说“运行脚本”“试试”“测试它”“它能工作吗”,且脚本文件有本地修改,应使用 script preview;不要把脚本推送后再 script run,因为推送即部署,为测试而部署会用未测试的改动覆盖工作区版本。仅在用户明确说“运行已部署版本”或没有被编辑的本地脚本时使用 script run;仅在用户明确要求部署/发布/推送,或预览已验证且用户希望进入工作区时使用 sync push。

九、编辑后保持元数据同步 wmill-lock.yaml 为每个条目记录内容哈希。编辑脚本内容(尤其是增删 import 或更改 main 参数)会使该哈希失效,令 .lock、.script.yaml 输入 schema 和哈希行过期。此类编辑后应运行 wmill generate-metadata(限定于改动范围),使解析后的 lock、自动生成的 args UI 和 wmill-lock.yaml 与代码匹配;否则会在 git-sync 和 CI 中产生虚假差异。该命令只写本地文件(不是部署),但会重新解析依赖,可能提升未锁定版本。默认应提出并等用户同意后再运行,除非项目的 AGENTS.md 选择自动运行。无论如何都由你来运行该命令,而不是用户。运行后对比重新生成的 .lock / .script.lock 文件,并告知用户哪些依赖版本变化(例如 requests 2.31.0 → 2.32.0),以便在部署前发现不想要的版本提升。要在代码中固定版本以保持不变。无路径参数时,generate-metadata 只重新生成内容哈希发生漂移的条目。导入会传播:编辑被其他脚本导入的脚本,会标记所有导入者为过期。若触及范围超出预期,可运行 wmill generate-metadata --dry-run 列出每个过期条目及原因,再用路径参数或 --strict-folder-boundaries 缩小范围。若磁盘上的 .lock 和 .script.yaml 已正确、仅需刷新 wmill-lock.yaml 哈希,可使用 wmill generate-metadata rehash。

十、编写后的测试建议 如果用户尚未要求运行/测试/预览脚本,应作为一句话的下一步提出(例如“Want me to run wmill script preview with sample args?”),不要展示多选项菜单。如果用户在原请求中已要求测试/运行/尝试,跳过提议,直接执行 wmill script preview <path> -d '<args>',并从脚本声明的参数中选取合理参数。参数形态因语言而异:代码语言为 main(...),SQL 为各自占位符语法,Bash 为位置参数 $1、$2 等,PowerShell 为 param(...)。wmill script preview 不部署,但仍会执行脚本代码并可能产生副作用;在用户要求测试/预览(或确认要执行)时自行运行。wmill generate-metadata 也不部署,仅写本地文件。部署到工作区是唯一会改变远程状态的一步,仅在用户明确要求时执行。若需要可视化地在开发页打开脚本预览,使用 preview 技能。可用 wmill resource-type list --schema 发现可用资源类型。

关于收费、价格、平台支持范围等信息,资料暂未提供。