108 lines
4.4 KiB
Markdown
108 lines
4.4 KiB
Markdown
# JS Runner Spec
|
||
|
||
## Purpose
|
||
|
||
Define requirements for the js-runner skill, which enables execution of JavaScript and TypeScript scripts using Bun runtime with automatic dependency management and temporary file handling.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 生成临时文件路径
|
||
辅助脚本 MUST 提供为脚本生成唯一临时文件路径的功能。
|
||
|
||
#### Scenario: 生成 JavaScript 临时路径
|
||
- **WHEN** 调用 `scripts/get_temp_path.js` 并传入参数 `'js'`
|
||
- **THEN** 返回操作系统的临时目录路径
|
||
- **THEN** 路径包含时间戳和随机字符串以确保唯一性
|
||
- **THEN** 文件扩展名为 `.js`
|
||
|
||
#### Scenario: 生成 TypeScript 临时路径
|
||
- **WHEN** 调用 `scripts/get_temp_path.js` 并传入参数 `'ts'`
|
||
- **THEN** 返回操作系统的临时目录路径
|
||
- **THEN** 路径包含时间戳和随机字符串以确保唯一性
|
||
- **THEN** 文件扩展名为 `.ts`
|
||
|
||
### Requirement: 文档描述完整调用流程
|
||
SKILL.md MUST 清晰描述大模型如何使用 js-runner 技能执行 JavaScript/TypeScript 脚本的完整流程。
|
||
|
||
#### 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** 文档提供完整的示例代码，展示：
|
||
- 如何检查 Bun 安装（`bun --version`）
|
||
- 如何调用辅助脚本生成临时文件路径
|
||
- 如何执行脚本
|
||
- 如何处理输出和错误
|
||
|
||
### Requirement: 错误处理和诊断
|
||
系统 MUST 提供清晰的错误信息和诊断功能，帮助用户识别和解决问题。
|
||
|
||
#### Scenario: 未安装 Bun 时的错误
|
||
- **WHEN** 系统未检测到 Bun 运行时
|
||
- **THEN** 系统输出友好的错误消息，说明需要安装 Bun
|
||
- **THEN** 系统提供安装指令（`curl -fsSL https://bun.sh/install | bash`）
|
||
- **THEN** 退出码指示依赖缺失
|
||
|
||
#### Scenario: 脚本语法错误
|
||
- **WHEN** 脚本包含语法错误
|
||
- **THEN** Bun 输出详细的语法错误信息（包括文件名、行号、错误描述）
|
||
- **THEN** 系统将这些信息传递给用户
|
||
- **THEN** 退出码指示语法错误
|
||
|
||
#### Scenario: 运行时错误
|
||
- **WHEN** 脚本执行过程中抛出运行时错误
|
||
- **THEN** 系统输出完整的错误堆栈跟踪
|
||
- **THEN** 临时文件路径被正确映射以便用户调试
|
||
- **THEN** 退出码指示运行时错误
|
||
|
||
### Requirement: 输出处理
|
||
系统 MUST 正确处理脚本的 stdout 和 stderr 输出，将其传递给用户终端。
|
||
|
||
#### Scenario: 标准输出
|
||
- **WHEN** 脚本使用 `console.log()` 或 `console.error()` 输出
|
||
- **THEN** 系统将输出实时传递到用户终端的 stdout 或 stderr
|
||
- **THEN** 不修改或过滤输出内容
|
||
|
||
#### Scenario: 退出码传递
|
||
- **WHEN** 脚本使用 `process.exit(n)` 显式退出
|
||
- **THEN** 系统使用该退出码
|
||
- **WHEN** 脚本正常完成且不调用 `process.exit()`
|
||
- **THEN** 系统使用退出码 0
|
||
|
||
### Requirement: 文档完整性
|
||
系统 MUST 包含完整的 SKILL.md 文档，说明如何使用 js-runner。
|
||
|
||
#### Scenario: SKILL.md 包含必要的 frontmatter
|
||
- **WHEN** 大模型阅读 SKILL.md
|
||
- **THEN** 文档顶部包含 YAML frontmatter
|
||
- **THEN** 包含 `name` 字段，值为 `js-runner`
|
||
- **THEN** 包含 `description` 字段，描述技能的功能和使用场景
|
||
- **THEN** 可选包含 `compatibility` 字段，说明 Bun 依赖
|
||
|
||
#### Scenario: 安装说明
|
||
- **WHEN** 用户阅读 SKILL.md
|
||
- **THEN** 文档包含 Bun 的安装说明和命令
|
||
- **THEN** 文档说明 js-runner 的依赖要求
|
||
|
||
#### Scenario: 使用示例
|
||
- **WHEN** 用户阅读 SKILL.md
|
||
- **THEN** 文档提供基本使用示例（执行简单脚本）
|
||
- **THEN** 文档提供使用外部依赖的示例（通过 import 直接引入，Bun 自动处理）
|
||
- **THEN** 文档提供 JavaScript 和 TypeScript 执行示例（同样流程）
|
||
- **THEN** 文档提供错误处理示例
|
||
|
||
#### Scenario: API 参考
|
||
- **WHEN** 用户阅读 SKILL.md
|
||
- **THEN** 文档列出所有可用命令行标志
|
||
- **THEN** 文档说明每个标志的作用和用法
|
||
- **THEN** 文档说明 `get_temp_path()` 辅助函数的用法
|
||
- **THEN** 文档说明 Bun 的自动依赖管理机制
|