统一skill命名

openspec/specs/lyxy-runner-js/spec.md

@@ -0,0 +1,160 @@
+# lyxy-runner-js Spec
+
+## Purpose
+
+Define requirements for the lyxy-runner-js skill, which enables execution of JavaScript and TypeScript scripts using Bun runtime with automatic dependency management and temporary file handling.
+
+## 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** 可以继续执行脚本的相应场景流程
+
+### 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 清晰描述大模型如何使用 lyxy-runner-js 技能执行 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** 快速参考帮助大模型快速选择正确的执行方式
+
+### 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 文档，说明如何使用 lyxy-runner-js。
+
+#### Scenario: SKILL.md 包含必要的 frontmatter
+- **WHEN** 大模型阅读 SKILL.md
+- **THEN** 文档顶部包含 YAML frontmatter
+- **THEN** 包含 `name` 字段，值为 `lyxy-runner-js`
+- **THEN** 包含 `description` 字段，描述技能的功能和使用场景
+- **THEN** 可选包含 `compatibility` 字段，说明 Bun 依赖
+
+#### Scenario: 安装说明
+- **WHEN** 用户阅读 SKILL.md
+- **THEN** 文档包含 Bun 的安装说明和命令
+- **THEN** 文档说明 lyxy-runner-js 的依赖要求
+
+#### 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 的自动依赖管理机制