101 lines
3.9 KiB
Markdown
101 lines
3.9 KiB
Markdown
## Context
|
||
|
||
js-runner 技能目前的标准流程假设所有脚本都需要通过临时文件执行。这种设计确保了脚本的隔离性和自动清理，但牺牲了灵活性。用户可能希望：
|
||
1. 执行已存在的脚本文件
|
||
2. 将脚本持久化到项目中的特定位置
|
||
3. 利用大模型已有的文件操作工具（Write）直接创建脚本
|
||
|
||
当前实现强制所有场景都通过 `get_temp_path.js` 生成临时路径，限制了这些使用场景。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- 在文档中增加条件判断逻辑，根据用户输入选择不同的执行路径
|
||
- 保持向后兼容：未指定路径时仍使用临时文件路径（场景3）
|
||
- 支持直接执行已存在的脚本文件（场景1）
|
||
- 支持使用大模型工具在指定路径创建脚本（场景2）
|
||
|
||
**Non-Goals:**
|
||
- 不修改 `get_temp_path.js` 的实现
|
||
- 不改变 Bun 运行时的行为
|
||
- 不增加新的辅助脚本或工具
|
||
|
||
## Decisions
|
||
|
||
### 决策1：文档驱动的实现方案
|
||
|
||
**决策选择：** 通过更新 SKILL.md 文档来定义新的使用流程，而不是修改代码实现。
|
||
|
||
**理由：**
|
||
- js-runner 的核心功能（脚本执行）已经完全由 Bun 运行时提供
|
||
- 大模型根据 SKILL.md 的描述来选择操作方式
|
||
- 当前代码（`get_temp_path.js`）在临时路径场景下已经完全满足需求
|
||
- 直接使用大模型的 Write 工具创建文件比通过辅助脚本更灵活
|
||
|
||
**替代方案考虑：**
|
||
- 方案A：修改 `get_temp_path.js` 增加路径参数 → 拒绝，因为增加了不必要的复杂性，大模型已有 Write 工具
|
||
- 方案B：创建新的辅助脚本用于自定义路径 → 拒绝，重复造轮子，大模型工具已覆盖此需求
|
||
|
||
### 决策2：场景优先级的设计
|
||
|
||
**决策选择：** 在文档中将场景分为明确的优先级，确保大模型在处理用户请求时有清晰的决策树。
|
||
|
||
**决策树：**
|
||
1. 用户是否提供了要执行的脚本文件路径？
|
||
- 是 → 直接执行（场景1）
|
||
- 否 → 进入下一步
|
||
2. 用户是否指定了脚本的生成路径？
|
||
- 是 → 用 Write 工具在指定路径创建脚本，然后执行（场景2）
|
||
- 否 → 使用 `get_temp_path.js` 生成临时路径，创建脚本，执行（场景3）
|
||
|
||
**理由：**
|
||
- 优先处理用户明确指定的意图（已有脚本或自定义路径）
|
||
- 临时路径作为兜底方案，确保未指定路径时仍能工作
|
||
- 决策树简单清晰，大模型易于理解和执行
|
||
|
||
### 决策3：保持 `get_temp_path.js` 不变
|
||
|
||
**决策选择：** 不修改任何现有代码，仅更新文档。
|
||
|
||
**理由：**
|
||
- 临时路径生成逻辑在场景3中仍然必需
|
||
- 增加参数会增加代码维护成本
|
||
- 文档更新比代码修改更容易审查和回滚
|
||
|
||
## Risks / Trade-offs
|
||
|
||
### 风险1：大模型可能不理解优先级逻辑
|
||
|
||
**风险：** 如果文档描述不够清晰，大模型可能在场景选择上出错。
|
||
|
||
**缓解措施：**
|
||
- 在文档中使用明确的"决策树"或"流程图"形式
|
||
- 为每个场景提供清晰的示例代码
|
||
- 在 SKILL.md 顶部使用简洁的"快速参考"部分总结三种场景
|
||
|
||
### 权衡：文档复杂度 vs 灵活性
|
||
|
||
**权衡：** 增加文档的复杂度来提供更高的灵活性。
|
||
|
||
**说明：**
|
||
- 用户获得了更多控制权（直接指定路径）
|
||
- 文档需要更详细地解释不同场景
|
||
- 但这符合 js-runner 作为"技能工具"的定位——为大模型提供灵活的执行选项
|
||
|
||
## Migration Plan
|
||
|
||
本变更仅涉及文档更新，无需代码迁移或部署步骤。
|
||
|
||
**更新步骤：**
|
||
1. 更新 `skills/js-runner/SKILL.md`，增加三种使用场景的说明
|
||
2. 更新 `openspec/specs/js-runner/spec.md`，增加新的需求场景
|
||
3. 验证文档描述是否清晰，易于理解和执行
|
||
|
||
**回滚策略：**
|
||
- 使用 git 版本控制可以轻松回滚文档修改
|
||
- 不涉及代码修改，回滚风险极低
|
||
|
||
## Open Questions
|
||
|
||
无。本变更的范围明确，技术实现路径清晰。
|