327 lines
8.1 KiB
Markdown
327 lines
8.1 KiB
Markdown
---
|
||
name: js-runner
|
||
description: Any task that requires Javascript/Typescript processing should use this skill.
|
||
compatibility: Requires Bun runtime (https://bun.sh)
|
||
---
|
||
|
||
# js-runner
|
||
|
||
基于 Bun 的 JavaScript/TypeScript 执行技能，提供隔离的脚本执行和自动依赖管理。
|
||
|
||
## 快速参考
|
||
|
||
根据您的需求选择使用方式：
|
||
|
||
| 场景 | 描述 | 命令 |
|
||
| --------- | ------------------------ | ---------------------------------- |
|
||
| **场景1** | 直接执行已存在的脚本文件 | `bun <script-file>` |
|
||
| **场景2** | 在指定路径创建脚本并执行 | 使用 Write 工具创建 → `bun <path>` |
|
||
| **场景3** | 使用临时路径执行（默认） | 生成临时路径 → `bun <temp-file>` |
|
||
|
||
**重要提示：** 所有场景在执行脚本前都必须先检查 Bun 环境：`bun --version`
|
||
|
||
## 前置条件
|
||
|
||
### 安装 Bun
|
||
|
||
js-runner 需要安装 Bun。Bun 是一个快速的 JavaScript 运行时，内置包管理器。
|
||
|
||
**macOS/Linux:**
|
||
|
||
```bash
|
||
curl -fsSL https://bun.sh/install | bash
|
||
```
|
||
|
||
**Windows:**
|
||
|
||
```powershell
|
||
powershell -c "irm bun.sh/install.ps1 | iex"
|
||
```
|
||
|
||
**验证安装:**
|
||
|
||
```bash
|
||
bun --version
|
||
```
|
||
|
||
## 使用流程
|
||
|
||
**执行流程决策树：**
|
||
|
||
1. **步骤1：检查 Bun 环境**
|
||
- 执行：`bun --version`
|
||
- 失败 → 输出错误信息（包含安装说明）并停止执行
|
||
- 成功 → 进入下一步
|
||
- **重要：** 禁止使用 nodejs、npm、yarn、pnpm 等其他工具
|
||
|
||
2. **步骤2：选择执行场景**
|
||
- 场景1：用户提供了已存在的脚本文件路径？
|
||
- 是 → 直接执行：`bun <script-file>`
|
||
- 否 → 进入下一步
|
||
- 场景2：用户指定了脚本的生成路径？
|
||
- 是 → 使用 Write 工具创建脚本，然后执行
|
||
- 否 → 进入场景3
|
||
|
||
3. **场景3（默认）**：使用临时路径执行
|
||
- 生成临时文件路径
|
||
- 将脚本内容写入临时文件
|
||
- 使用 Bun 运行脚本
|
||
- 临时文件由系统自动处理
|
||
|
||
---
|
||
|
||
### 场景1：执行已存在的脚本文件
|
||
|
||
```bash
|
||
# 步骤 1: 检查 Bun 是否已安装
|
||
bun --version
|
||
|
||
# 步骤 2: 直接执行已存在的脚本
|
||
bun ./scripts/my-script.js
|
||
|
||
# 脚本的输出将自动显示
|
||
```
|
||
|
||
**关键特点：**
|
||
- ✅ **无需生成临时文件** - 直接执行用户提供的脚本
|
||
- ✅ **保持脚本位置** - 脚本留在原位置，不会被移动或复制
|
||
- ✅ **简洁快速** - 跳过文件生成步骤，直接执行
|
||
|
||
### 场景2：在指定路径创建并执行脚本
|
||
|
||
```bash
|
||
# 步骤 1: 检查 Bun 是否已安装
|
||
bun --version
|
||
|
||
# 步骤 2: 使用 Write 工具在指定路径创建脚本
|
||
# (以下步骤由大模型使用 Write 工具完成)
|
||
# write content to "./scripts/new-script.js"
|
||
|
||
const greeting = "Hello from custom path!";
|
||
console.log(greeting);
|
||
|
||
# 步骤 3: 执行脚本
|
||
bun ./scripts/new-script.js
|
||
```
|
||
|
||
**关键特点：**
|
||
- ✅ **自定义路径** - 脚本创建到用户指定的位置
|
||
- ✅ **持久化存储** - 脚本文件保存在指定位置，不会被自动清理
|
||
- ✅ **灵活控制** - 用户可以精确控制脚本位置和命名
|
||
|
||
### 场景3：使用临时路径执行（默认流程）
|
||
|
||
当用户未提供任何路径信息时，使用临时路径执行脚本（默认流程）：
|
||
|
||
#### 基础示例
|
||
|
||
```bash
|
||
# 步骤 1: 检查 Bun 是否已安装
|
||
bun --version
|
||
|
||
# 步骤 2: 生成临时文件路径
|
||
TEMP_FILE=$(bun skills/js-runner/scripts/get_temp_path.js js)
|
||
|
||
# 步骤 3: 将脚本内容写入临时文件
|
||
cat <<EOF > "$TEMP_FILE"
|
||
const greeting = "Hello from js-runner!";
|
||
console.log(greeting);
|
||
EOF
|
||
|
||
# 步骤 4: 执行脚本
|
||
bun "$TEMP_FILE"
|
||
|
||
# 步骤 5: 输出已在上面捕获
|
||
# 临时文件将由系统自动清理
|
||
```
|
||
|
||
#### TypeScript 示例
|
||
|
||
```bash
|
||
# 生成 TypeScript 临时文件
|
||
TEMP_TS=$(bun skills/js-runner/scripts/get_temp_path.js ts)
|
||
|
||
# 写入 TypeScript 脚本
|
||
cat <<EOF > "$TEMP_TS"
|
||
const message: string = 'TypeScript execution';
|
||
console.log(message);
|
||
EOF
|
||
|
||
# 执行 - Bun 会自动转译 TypeScript
|
||
bun "$TEMP_TS"
|
||
```
|
||
|
||
**Bun 自动处理：**
|
||
- 检测 `import` 语句
|
||
- 即时转译 TypeScript
|
||
- 下载并缓存依赖（到 `~/.bun/install/cache`）
|
||
- 无需 `package.json` 或手动安装
|
||
|
||
## 依赖管理
|
||
|
||
Bun 提供自动依赖管理，无需手动配置：
|
||
|
||
### 导入外部包
|
||
|
||
```javascript
|
||
// ESM import（推荐）
|
||
import axios from 'axios'
|
||
import lodash from 'lodash'
|
||
|
||
// CommonJS import（也支持）
|
||
const axios = require('axios')
|
||
```
|
||
|
||
首次执行带有外部导入的脚本时，Bun 会：
|
||
|
||
1. 分析导入
|
||
2. 从 npm 下载缺失的依赖
|
||
3. 全局缓存到 `~/.bun/install/cache`
|
||
4. 后续运行使用缓存版本
|
||
|
||
### 不需要 package.json
|
||
|
||
与 Node.js 不同，你无需创建 `package.json` 或单独运行 `bun install`。Bun 在运行时自动处理所有操作。
|
||
|
||
## 辅助函数 API
|
||
|
||
### `get_temp_path.js`
|
||
|
||
为脚本执行生成唯一的临时文件路径。
|
||
|
||
**CLI 使用方式:**
|
||
|
||
```bash
|
||
bun skills/js-runner/scripts/get_temp_path.js <extension>
|
||
```
|
||
|
||
**参数:**
|
||
|
||
- `extension` (可选): 文件扩展名。默认为 `js`。常用值: `js`, `ts`, `mjs`, `mts`
|
||
|
||
**输出:** 返回类似 `/var/folders/.../js-runner-1234567890-abc123.js` 的路径
|
||
|
||
**路径格式:**
|
||
|
||
- 使用操作系统临时目录（Unix 上为 `/tmp`，Windows 上为 `%TEMP%`）
|
||
- 前缀: `js-runner-`
|
||
- 时间戳: 自纪元以来的毫秒数
|
||
- 随机字符串: 7 字符字母数字
|
||
- 扩展名: 参数中提供的值
|
||
|
||
**示例:**
|
||
|
||
```bash
|
||
$ bun skills/js-runner/scripts/get_temp_path.js js
|
||
/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/js-runner-1770257905333-na6ujx.js
|
||
|
||
$ bun skills/js-runner/scripts/get_temp_path.js ts
|
||
/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/js-runner-1770257905333-v8yzt.ts
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
### 未安装 Bun
|
||
|
||
**症状:** `bun --version` 失败或返回 "command not found: bun"
|
||
|
||
**错误处理：**
|
||
|
||
当检测到 Bun 未安装时，必须：
|
||
|
||
1. **停止执行** - 不进行任何后续操作
|
||
2. **输出明确错误信息** - 清晰说明 "Bun 运行时未安装" 或类似提示
|
||
3. **提供安装说明** - 参考"前置条件"章节的安装命令
|
||
|
||
**重要限制：**
|
||
|
||
- ❌ **禁止自动安装** - 不要尝试自动安装 Bun，由用户自行决定
|
||
- ❌ **禁止使用其他工具** - 不要尝试使用 nodejs、npm、yarn、pnpm 等其他 JavaScript 运行时或包管理工具
|
||
- ❌ **禁止格式转换** - 不要建议用户将脚本转换为其他运行时格式
|
||
|
||
**正确做法：**
|
||
|
||
- ✅ 仅输出错误信息和安装说明
|
||
- ✅ 等待用户安装 Bun 后再继续
|
||
- ✅ 保持使用 Bun 作为唯一运行时
|
||
|
||
### 脚本语法错误
|
||
|
||
Bun 提供详细的语法错误信息：
|
||
|
||
```bash
|
||
$ bun "$TEMP_FILE"
|
||
error: Unexpected token
|
||
--> /var/folders/.../script.js:2:10
|
||
|
|
||
2 | const = 123;
|
||
| ^
|
||
```
|
||
|
||
错误信息包括：
|
||
|
||
- 文件路径和行号
|
||
- 错误的确切位置
|
||
- 问题描述
|
||
|
||
### 运行时错误
|
||
|
||
运行时错误包含完整的堆栈跟踪：
|
||
|
||
```bash
|
||
$ bun "$TEMP_FILE"
|
||
ReferenceError: foo is not defined
|
||
at script.js:3:5
|
||
at main (script.js:1:1)
|
||
```
|
||
|
||
### 其他错误
|
||
|
||
其他任何形式的错误都原样输出
|
||
|
||
## 输出处理
|
||
|
||
### 标准输出
|
||
|
||
所有 `console.log()`, `console.info()`, `console.warn()` 输出都到 stdout：
|
||
|
||
```bash
|
||
bun "$TEMP_FILE" # stdout 由调用代码捕获
|
||
```
|
||
|
||
### 错误输出
|
||
|
||
`console.error()` 输出到 stderr：
|
||
|
||
```bash
|
||
bun "$TEMP_FILE" 2>error.log # 单独捕获 stderr
|
||
```
|
||
|
||
### 退出码
|
||
|
||
脚本可以设置自定义退出码：
|
||
|
||
```javascript
|
||
process.exit(1) // 错误
|
||
process.exit(0) // 成功
|
||
```
|
||
|
||
调用者接收这些退出码以确定执行状态。
|
||
|
||
## 临时文件管理
|
||
|
||
执行后 **不会主动删除** 临时文件。这是设计使然：
|
||
|
||
- 操作系统自动管理临时目录空间
|
||
- 文件可以保留用于调试目的
|
||
- 大多数操作系统定期清理旧的临时文件
|
||
|
||
## 最佳实践
|
||
|
||
1. **始终先检查 Bun 环境** - 所有场景第一步都执行 `bun --version`
|
||
2. **根据用户意图选择场景** - 查看快速参考选择合适的使用方式
|
||
3. **单独处理 stdout/stderr** - 以区分输出和错误
|
||
4. **检查退出码** - 以检测脚本失败
|
||
5. **使用 ESM imports** - 使用 `import from` 编写现代 JavaScript
|
||
6. **捕获并显示错误** - 以帮助用户调试问题
|