Skill/openspec/changes/archive/2026-02-06-js-runner-custom-path/specs/js-runner/spec.md

ADDED Requirements

Requirement: 环境检查前置条件

在任何场景执行脚本之前，大模型 MUST 先检查 Bun 运行时是否可用。

Scenario: 所有场景的环境检查

• WHEN 大模型准备执行脚本（无论使用哪种场景）
• THEN 必须在执行任何脚本之前先运行 bun --version
• THEN 如果 bun --version 失败或未找到命令，必须输出友好的错误信息
• THEN 错误信息必须明确说明 "Bun 运行时未安装" 或类似提示
• THEN 错误信息必须包含 Bun 安装说明（如 curl -fsSL https://bun.sh/install | bash）
• THEN 环境检查失败时必须停止后续执行
• THEN 大模型禁止自动尝试使用 nodejs、npm、yarn、pnpm 等其他 JavaScript 运行时或包管理工具
• THEN 大模型禁止建议用户将脚本转换为其他运行时格式
• WHEN bun --version 成功
• THEN 可以继续执行脚本的相应场景流程

MODIFIED Requirements

Requirement: 文档描述完整调用流程

SKILL.md MUST 清晰描述大模型如何使用 js-runner 技能执行 JavaScript/TypeScript 脚本的完整流程，并根据用户提供的路径信息选择不同的执行方式。

Scenario: 执行已存在的脚本文件

• WHEN 用户提供已存在的脚本文件路径
• THEN 首先执行 bun --version 检查环境
• THEN 如果环境检查失败，输出错误信息并停止执行
• THEN 环境检查通过后，大模型直接使用 bun <script-file> 执行该脚本
• THEN 跳过 get_temp_path.js 调用
• THEN 不创建任何新文件
• THEN 使用脚本的 stdout 和 stderr 作为输出

Scenario: 在指定路径创建并执行脚本

• WHEN 用户提供脚本生成路径（但脚本文件不存在）
• THEN 首先执行 bun --version 检查环境
• THEN 如果环境检查失败，输出错误信息并停止执行
• THEN 环境检查通过后，大模型使用 Write 工具在指定路径创建脚本文件
• THEN 使用 bun <specified-path> 执行该脚本
• THEN 跳过 get_temp_path.js 调用
• THEN 脚本文件持久化到指定位置

Scenario: 使用临时路径执行脚本（默认流程）

• WHEN 大模型阅读 SKILL.md 且用户未提供脚本路径或生成路径
• THEN 文档描述以下标准流程：
  1. 执行 bun --version 检查环境
  2. 调用 scripts/get_temp_path.js 生成临时文件路径
  3. 将脚本内容写入临时文件
  4. 使用 bun <temp-file> 执行脚本
  5. Bun 自动处理依赖和 TypeScript 转译
  6. 临时文件由系统自动清理

Scenario: 文档包含场景选择决策树

• WHEN 大模型阅读 SKILL.md
• THEN 文档提供清晰的执行流程决策树：
  1. 首先执行 bun --version 检查环境
     • 失败 → 输出错误信息并停止
     • 成功 → 进入下一步
  2. 用户是否提供了已存在的脚本文件路径？
     • 是 → 场景1：直接执行
     • 否 → 进入下一步
  3. 用户是否指定了脚本的生成路径？
     • 是 → 场景2：在指定路径创建脚本，然后执行
     • 否 → 场景3：使用临时路径（默认）

Scenario: 文档中的示例代码（三种场景）

• WHEN 大模型阅读 SKILL.md
• THEN 文档提供完整的示例代码，展示：
  • 场景1示例：直接执行已存在的脚本文件
  • 场景2示例：在指定路径创建脚本并执行
  • 场景3示例：使用临时路径执行脚本（包含如何调用辅助脚本生成临时文件路径）
  • 如何检查 Bun 安装（bun --version）
  • 如何处理输出和错误

Scenario: 快速参考部分

• WHEN 大模型阅读 SKILL.md
• THEN 文档顶部包含快速参考部分
• THEN 快速参考简洁地总结三种使用场景的关键命令
• THEN 快速参考帮助大模型快速选择正确的执行方式