用途:在创建任何独立单文件脚本、自动化任务或小型 CLI 工具时加载本技能,提供具体脚本模式,包括脚本与项目的选择、目录布局、脚本体结构以及 CLI 与信号处理的默认约定。
前置条件:加载前需先加载 engineering-principles,它提供严格类型、边界处校验、显式错误与「原则优先于规定」的基础。本技能补充脚本层面的落地模式。
脚本还是完整项目:一次性任务、单文件、无需测试、模板生成或自动化、直接由源码运行、依赖内联或写在最小头部、约 500 行以内,适合单脚本;多特性、需要测试、带 UI 或 API、经任务运行器或构建步骤运行、依赖写在项目清单、会超过约 500 行,应改为项目布局。
脚本布局:辅助文件与脚本放在一起,仅保留只含 linter 与类型检查器设置的最小工具配置清单,不要项目元数据或依赖声明。示例目录含 script、template.ext、schema.ext、configs/、tool-config、.gitignore。
脚本体结构:分为常量与类型、工具与辅助、业务逻辑、CLI 接口四段。业务逻辑为纯函数,不做底层 I/O;CLI 段是薄适配层,解析参数、调用一个业务函数或小流水线、把结果映射到 stdout/stderr 与退出码。
CLI 约定:除 --help 外始终支持 -h;使用生态内优秀 CLI 库(Python 用 typer,Node 用 commander 或 yargs),仅在无法引入外部依赖时用标准库解析器;显式把错误映射为退出码,预期失败写 stderr 并返回非零退出码;不在参数处理里写业务逻辑。
优雅退出:Ctrl+C 不应打印堆栈,捕获中断后干净退出,遵循 Unix 约定用退出码 130;若脚本派生进程,使用进程组使 Ctrl+C 终止整棵进程树;对长驻子进程先发 SIGTERM,超时后再 SIGKILL。
示例要点:Python 使用 PEP 723 内联元数据与 uv run --script 或 shebang 直接执行,typer 构建 CLI,pyproject.toml 仅保留 [tool.pyright]、[tool.ruff] 等工具配置;TypeScript/Bun 使用 bun shebang,Bun 首次运行自动安装依赖,无需 package.json,用 commander 解析 CLI、zod 做配置校验、neverthrow 表示预期错误,脚本相对路径使用 import.meta.dir;若必须在 Node 下运行,可用 tsx 或 node myscript.ts,但选择前需确认当前 Node 原生类型擦除的限制。这些默认仅适用于单文件脚本,维护型应用项目应遵循项目搭建相关规范。
限制与衔接:脚本超过约 500 行或需要测试与完整项目布局时,应交给项目搭建技能;Python 类型系统、错误处理与异步模式参考 writing-python-code。本资料未提供具体收费、平台支持与效果数据。