增加js-runner的skill

2026-02-05 11:25:01 +08:00
parent a3169930fd
commit 9e42c2ccd9
9 changed files with 717 additions and 0 deletions
--- a/openspec/changes/archive/2026-02-05-bun-js-runner/.openspec.yaml
+++ b/openspec/changes/archive/2026-02-05-bun-js-runner/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-05
--- a/openspec/changes/archive/2026-02-05-bun-js-runner/design.md
+++ b/openspec/changes/archive/2026-02-05-bun-js-runner/design.md
@@ -0,0 +1,143 @@
+## Context（背景）
+
+本项目在 `skills/` 目录下开发用于大模型工具的技能（skills），每个子目录代表一个技能。目前，项目已经有一个 `python-runner` 技能，它使用 `uv` 提供了隔离的 Python 执行环境，支持依赖管理和临时文件隔离。
+
+`js-runner/` 目录已存在但未完成，只包含一个测试文件（`test/axios.js`）。目前项目中还没有功能完整的 JavaScript/TypeScript 执行能力。
+
+**当前状态：**
+- `python-runner` 技能已完整实现（基于 uv 的隔离）
+- `js-runner` 目录骨架存在但缺少实现
+- 没有 JavaScript/TypeScript 的依赖管理机制
+- 没有 JS/TS 脚本的临时文件生命周期管理
+
+**约束条件：**
+- 必须保持环境隔离（不污染系统包）
+- 应遵循 `python-runner` 建立的模式以保持一致性
+- 技能结构必须符合项目规范（`skills/<skill-name>/`）
+- 必须同时支持 JavaScript 和 TypeScript 执行
+
+## Goals / Non-Goals（目标 / 非目标）
+
+**目标：**
+- 提供辅助脚本供大模型调用（使用 JavaScript 编写，与 skill 主题一致）
+- 在 SKILL.md 中清晰描述完整的调用流程
+- 利用 Bun 的自动依赖管理能力
+- 匹配 `python-runner` 的工作流程和用户体验，保持一致性
+
+**非目标：**
+- 提供完整的 IDE 或开发环境
+- 脚本的长期存储或持久化
+- 超越 JavaScript/TypeScript 的多语言支持
+- 替换或修改现有的 `python-runner` 技能
+- 构建自定义的 Bun 运行时包装器（直接使用 Bun）
+
+## Decisions（技术决策）
+
+### 1. 使用 Bun 作为 JavaScript 运行时
+
+**理由：** Bun 相比替代方案具有显著优势：
+- **Bun：** 比 Node.js 快约 100 倍的冷启动，内置包管理器（bun install），原生 TypeScript 支持，兼容 Node.js API
+- **Node.js + npm/yarn：** 启动慢，需要外部包管理器，没有原生 TypeScript 支持
+- **Deno：** 不同的 API 表面（不兼容 Node.js），生态系统较小，Node.js 用户学习曲线陡峭
+
+**考虑的替代方案：**
+- **Node.js with npm：** 因启动速度慢且无原生 TypeScript 支持而被拒绝
+- **Deno：** 因 API 与 Node.js 生态不兼容且包管理不熟悉而被拒绝
+
+### 2. 基于临时文件的执行模型
+
+**理由：** 遵循 `python-runner` 的模式，在临时文件中执行脚本可以：
+- 在执行之间保持干净的隔离
+- 自动清理产物
+- 不需要跨运行的状态管理
+- 比内存执行实现更简单
+
+**考虑的替代方案：**
+- **通过 Bun 的 `Bun.transpileString()` 进行内存执行：** 因对模块导入和外部依赖支持不好而被拒绝
+- **持久化目录结构：** 因避免执行之间的状态泄漏而被拒绝
+
+### 3. 使用 Bun 的自动依赖管理
+
+**理由：** Bun 可以直接运行脚本并自动处理依赖：
+- **自动依赖解析：** 当脚本使用 `import` 或 `require` 引入外部包时，Bun 自动下载并缓存该包
+- **无需手动安装：** 不需要手动运行 `bun install`，Bun 在运行时自动处理
+- **智能缓存：** Bun 全局缓存已下载的包，后续运行无需重复下载
+- **简化实现：** 不需要生成临时的 `package.json`，也不需要管理 `node_modules`
+
+**工作流程：**
+1. 用户直接运行脚本（内联或从文件）
+2. 脚本中使用 `import` 或 `require` 引入依赖（如 `import axios from 'axios'`）
+3. Bun 自动检测到未安装的依赖
+4. Bun 下载并缓存依赖到 Bun 的全局缓存（`~/.bun/install/cache`）
+5. 执行脚本
+6. 清理临时脚本文件（Bun 的缓存保持不变）
+
+**考虑的替代方案：**
+- **手动 package.json + bun install：** 因 Bun 已经提供自动依赖处理而被拒绝（过度设计）
+- **要求用户提供 package.json：** 因增加用户负担而被拒绝
+
+### 4. 用于路径管理的辅助脚本
+
+**理由：** `get_temp_path.js` 辅助脚本将：
+- 为脚本生成唯一的临时文件路径
+- 遵循特定于操作系统的临时目录约定
+- 使用 JavaScript 编写，与 js-runner 主题一致
+- 使用 Bun 运行（已确保环境就绪）
+
+**实现方式：**
+```javascript
+import { tmpdir } from "os";
+import { join } from "path";
+
+export function getTempPath(extension) {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(7);
+  return join(tmpdir(), `js-runner-${timestamp}-${random}.${extension}`);
+}
+```
+
+## Risks / Trade-offs（风险 / 权衡）
+
+### 风险：需要安装 Bun
+
+**风险：** 用户必须单独安装 Bun，这增加了设置障碍。
+
+**缓解措施：**
+- 在 SKILL.md 中清晰记录安装过程（`curl -fsSL https://bun.sh/install | bash`）
+- 如果未找到 Bun，提供有用的错误消息
+- 考虑添加 "check" 命令来验证 Bun 安装
+
+## Migration Plan（迁移计划）
+
+由于这是一个没有现有生产使用的新技能：
+
+1. **第一阶段：实现**
+   - 创建 `scripts/get_temp_path.js` 辅助脚本（使用 JavaScript 编写）
+   - 编写完整的 `SKILL.md` 文档，包含必要的 frontmatter
+   - 描述完整调用流程
+
+2. **第二阶段：验证**
+   - 验证 `get_temp_path.js` 辅助脚本工作正常
+   - 验证 SKILL.md 格式符合 Agent Skills 规范
+   - 验证 SKILL.md 中的调用流程准确无误
+
+3. **第三阶段：文档**
+   - 确保 SKILL.md 涵盖所有用例
+   - 为常见场景提供示例
+   - 记录错误处理和故障排除
+
+**回滚策略：**
+- 如果实现有问题，删除 `skills/js-runner/` 目录
+- 对项目其他部分无影响，因为这是一个新的隔离技能
+
+## Open Questions（待解决的问题）
+
+1. **我们是否应该支持持久化项目目录？**
+   - 当前方法：只有临时文件
+   - 考虑：允许用户指定工作目录
+   - 决策：推迟到未来增强；首先专注于简单的脚本执行
+
+2. **需要什么级别的错误报告？**
+   - 当前计划：按原样转发 Bun 的 stderr 输出
+   - 考虑：解析并美化常见错误
+   - 决策：从原始输出开始，根据用户需求增强
--- a/openspec/changes/archive/2026-02-05-bun-js-runner/proposal.md
+++ b/openspec/changes/archive/2026-02-05-bun-js-runner/proposal.md
@@ -0,0 +1,32 @@
+## Why
+
+当前项目已有基于uv的Python执行环境(python-runner)，但缺少相应的JavaScript/TypeScript执行能力。Bun作为现代JavaScript运行时，具有极快的启动速度、内置包管理器和对标准库的完整支持，非常适合创建一个类似python-runner的隔离式JS/TS执行环境，保持系统环境整洁。
+
+## What Changes
+
+- 完善现有的`skills/js-runner/`目录（目前仅有test/axios.js文件）
+- 基于Bun实现JavaScript/TypeScript脚本执行能力，使用临时文件和环境隔离
+- 参考python-runner的工作流，支持依赖管理（通过package.json或内联声明）
+- 提供辅助脚本生成临时文件路径
+- 创建完整的SKILL.md文档
+
+## Capabilities
+
+### New Capabilities
+- `js-runner`: 提供基于Bun的JavaScript/TypeScript脚本执行能力，支持依赖管理、环境隔离和临时文件清理
+
+### Modified Capabilities
+- None
+
+## Impact
+
+**新增文件**:
+- `skills/js-runner/SKILL.md` - Skill文档
+- `skills/js-runner/scripts/get_temp_path.js` - 临时路径生成辅助脚本
+
+**外部依赖**:
+- 需要安装Bun运行时（https://bun.sh）
+
+**不影响的范围**:
+- 不影响现有的python-runner skill
+- 不修改其他skill的实现
--- a/openspec/changes/archive/2026-02-05-bun-js-runner/specs/js-runner/spec.md
+++ b/openspec/changes/archive/2026-02-05-bun-js-runner/specs/js-runner/spec.md
@@ -0,0 +1,101 @@
+## ADDED 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 的自动依赖管理机制
--- a/openspec/changes/archive/2026-02-05-bun-js-runner/tasks.md
+++ b/openspec/changes/archive/2026-02-05-bun-js-runner/tasks.md
@@ -0,0 +1,51 @@
+## 1. 项目设置和目录结构
+
+- [x] 1.1 验证 `skills/js-runner/` 目录结构
+- [x] 1.2 创建 `skills/js-runner/scripts/` 目录（注意是复数 scripts/）
+- [x] 1.3 确认现有测试文件 `skills/js-runner/test/axios.js` 的状态
+- [x] 1.4 验证 Bun 运行时是否已安装（本地开发环境）
+
+## 2. 实现临时路径生成辅助脚本
+
+- [x] 2.1 创建 `skills/js-runner/scripts/get_temp_path.js` 文件（使用 JavaScript）
+- [x] 2.2 实现 `getTempPath(extension)` 函数
+- [x] 2.3 确保函数生成唯一路径（包含时间戳和随机字符串）
+- [x] 2.4 测试辅助脚本的输出格式正确性
+- [x] 2.5 使用 `bun scripts/get_temp_path.js` 验证脚本可执行
+
+## 3. 编写 SKILL.md 文档
+
+- [x] 3.1 创建 `skills/js-runner/SKILL.md` 文档
+- [x] 3.2 添加必要的 YAML frontmatter：
+  - `name: js-runner`
+  - `description` 描述功能和场景
+  - 可选 `compatibility` 说明 Bun 依赖
+- [x] 3.3 编写 Bun 安装说明和先决条件
+- [x] 3.4 描述完整的调用流程（供大模型使用）：
+  - 执行 `bun --version` 检查环境
+  - 调用 `scripts/get_temp_path.js` 生成临时文件路径
+  - 写入脚本内容到临时文件
+  - 使用 `bun <temp-file>` 执行脚本
+  - 输出结果到 stdout/stderr
+- [x] 3.5 添加调用流程的完整示例代码
+- [x] 3.6 添加依赖管理示例（通过 import 直接引入，Bun 自动处理）
+- [x] 3.7 添加 JavaScript 和 TypeScript 执行示例（同样流程）
+- [x] 3.8 添加错误处理和故障排除指南
+- [x] 3.9 添加辅助函数 API 参考
+- [x] 3.10 说明不主动清理临时文件，由系统自动处理
+
+## 4. 验证 SKILL.md 格式
+
+- [x] 4.1 使用 `skills-ref validate ./skills/js-runner` 验证格式（如果可用）
+- [x] 4.2 确认 frontmatter 符合 Agent Skills 规范
+- [x] 4.3 确认 name 字段格式正确（小写、数字、连字符）
+- [x] 4.4 确认 description 字段长度在 1024 字符以内
+- [x] 4.5 确认文档内容清晰且易于理解
+
+## 5. 集成和最终验证
+
+- [x] 5.1 手动测试 `scripts/get_temp_path.js` 辅助脚本
+- [x] 5.2 验证 SKILL.md 格式符合规范
+- [x] 5.3 验证调用流程的可行性
+- [x] 5.4 验证与 `python-runner` 模式的一致性
+- [x] 5.5 提交所有更改到版本控制（如适用）
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -4,3 +4,4 @@ context: |
    忽略项目目录下的「.opencode」和「opencode」两个目录，与开发的skill无关；
    这个项目是专门用于开发用于大模型工具的 skill；
    所有开发的 skill 都放在「skills」目录下，每个子目录都代表一个 skill，目录名为 skill 的名称；
+    开发过程中的文档使用中文，面向中文开发者进行交流；
--- a/openspec/specs/js-runner/spec.md
+++ b/openspec/specs/js-runner/spec.md
@@ -0,0 +1,107 @@
+# 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 的自动依赖管理机制