---
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. **捕获并显示错误** - 以帮助用户调试问题