规范命名

openspec/changes/archive/2026-02-04-python-runner/design.md

@@ -0,0 +1,234 @@
+## Context
+
+当前项目中还没有skill实现，需要创建第一个skill来指导大模型使用uv运行Python脚本。该项目专门用于开发大模型工具技能，所有skill都放在`skills`目录下，每个子目录代表一个skill。
+
+Python环境管理是一个常见问题：大模型在处理各种任务时经常需要执行Python脚本（数据分析、API测试、文件操作等），传统做法需要在系统Python环境预安装依赖，导致环境污染、版本冲突等问题。
+
+uv是Astral开发的快速Python包管理器，支持PEP 723内联元数据格式，可以在脚本中声明依赖，并在隔离环境中执行，自动管理虚拟环境和依赖安装。这为解决环境隔离问题提供了标准化的解决方案。
+
+**约束条件：**
+- skill文件遵循特定格式：YAML前置元数据 + Markdown内容
+- skill必须是指导型的，不直接执行代码
+- 不支持命令行参数或stdin输入
+- 不支持持久化环境
+- 严格错误处理模式
+- 必须支持Windows、macOS、Linux三个平台的临时目录处理
+
+**利益相关者：**
+- 大模型：需要清晰的模式指导来生成符合规范的Python脚本
+- 最终用户：通过大模型获得环境隔离的Python执行能力
+
+## Goals / Non-Goals
+
+**Goals:**
+- 创建指导大模型使用uv执行Python脚本的通用skill
+- 提供符合PEP 723规范的脚本编写模式
+- 确保环境隔离，不污染系统Python环境
+- 严格错误处理，任何错误都停止并给出清晰提示
+- 临时文件使用系统目录，系统自动清理
+- 适用于任何Python可处理的任务（数据处理、API交互、文件操作等）
+- 支持Windows、macOS、Linux跨平台自动适配临时目录
+
+**Non-Goals:**
+- 不直接执行用户提供的Python代码（只指导大模型）
+- 不支持命令行参数传递给脚本
+- 不支持从stdin读取输入
+- 不支持持久化虚拟环境（每次都是临时隔离环境）
+- 不支持自定义Python版本约束（使用uv默认版本）
+- 不支持复杂的依赖版本约束解析
+- 不处理动态import语句
+
+## Decisions
+
+### Decision 1: 技能定位为指导型而非执行型
+
+**决策：** skill提供指导模式和最佳实践，不直接执行Python代码。
+
+**理由：**
+- skill的主要用户是大模型，而不是最终用户
+- 大模型需要理解"如何用uv执行"的模式和规范
+- 保持skill的通用性，可以适应各种任务场景
+
+**替代方案考虑：**
+- 执行型skill：直接接收Python代码并执行
+  - ❌ 需要处理更多边界情况（代码注入、安全性等）
+  - ❌ 限制了灵活性（无法指导大模型编写更复杂的脚本）
+  - ❌ 增加了复杂度
+
+### Decision 2: 使用辅助脚本实现跨平台临时目录
+
+**决策：** 创建`skills/python-runner/script/get_temp_path.py`辅助脚本，使用Python标准库的`tempfile`模块在系统临时目录中创建空的Python脚本文件，并返回脚本文件路径。**辅助脚本本身也使用uv run执行，保持一致性。**
+
+**理由：**
+- `tempfile.gettempdir()`自动适配所有平台（Windows/macOS/Linux）
+- 避免了大模型需要检测平台和记住不同路径的复杂度
+- 辅助脚本直接创建临时Python脚本文件，大模型直接得到脚本文件路径
+- 简化大模型工作流：无需拼接路径，直接使用返回的文件路径写入内容
+- 使用Python标准库，保证跨平台兼容性
+- 辅助脚本可以复用，逻辑集中管理
+- **使用uv run执行辅助脚本，保持skill内所有Python脚本使用统一方式**
+
+**辅助脚本设计：**
+- **功能**：在系统临时目录创建空的Python脚本文件，返回文件路径
+- **无注释**：脚本只包含必要代码，没有文档字符串或注释
+- **PEP 723格式**：包含空的依赖声明`# dependencies = []`
+- **执行方式**：`uv run skills/python-runner/script/get_temp_path.py`
+- **输出**：直接在stdout输出临时Python脚本文件的完整路径
+  - Linux/macOS: `/tmp/uv_script_xxx.py`
+  - Windows: `C:\Users\<username>\AppData\Local\Temp\uv_script_xxx.py`
+
+**大模型使用流程：**
+1. 调用辅助脚本获取临时脚本文件路径（使用相对路径`./script/get_temp_path.py`，相对于SKILL.md所在目录）
+   ```bash
+   temp_file_path=$(uv run ./script/get_temp_path.py)
+   ```
+2. 在返回的脚本文件路径中直接写入PEP 723脚本内容：
+   ```python
+   # 使用大模型的Write工具
+   with open(temp_file_path, 'w') as f:
+       f.write(script_content)
+   ```
+3. 使用`uv run`执行脚本：
+   ```bash
+   uv run $temp_file_path
+   ```
+4. 系统自动清理临时文件，无需手动管理
+
+**替代方案考虑：**
+- 在辅助脚本中导出函数供导入：
+  - ❌ 需要大模型导入模块并调用函数，增加了复杂度
+  - ❌ 辅助脚本需要更多代码（函数定义、文档等）
+  - ❌ 不符合"简单直接"的设计原则
+- 在skill文档中说明平台差异：
+  - ❌ 大模型需要检测平台，容易出错
+  - ❌ 文档冗长，增加了复杂度
+  - ❌ 不符合"简化使用模式"的设计目标
+
+### Decision 3: 依赖声明使用无版本约束的包名
+
+**决策：** 在PEP 723元数据块中只声明包名，不指定版本约束，让uv自动选择兼容的最新版本。
+
+**理由：**
+- 简化依赖声明，降低大模型的认知负担
+- uv的依赖解析器会自动选择兼容版本
+- 使用最新版本通常更安全（包含安全修复）
+- 避免版本固定带来的兼容性问题
+
+**替代方案考虑：**
+- 固定版本号（如`pandas==2.1.0`）：
+  - ❌ 需要大模型了解每个包的最新版本
+  - ❌ 版本过时可能引入安全漏洞
+  - ❌ 可能与其他包产生版本冲突
+  - ❌ 增加维护成本
+
+### Decision 4: 严格错误处理模式
+
+**决策：** 任何错误条件都停止任务并显示清晰错误消息。错误类型包括：uv未安装、Python语法错误、依赖解析失败、脚本运行时错误。
+
+**理由：**
+- 严格模式符合skill作为工具的定位（可靠、可预测）
+- 避免错误传播导致难以调试的问题
+- 清晰的错误消息帮助大模型和用户快速定位问题
+- 保留失败的临时文件便于调试
+
+**替代方案考虑：**
+- 宽松模式（跳过错误包继续执行）：
+  - ❌ 可能导致部分依赖缺失的脚本执行
+  - ❌ 错误难以定位和调试
+  - ❌ 不符合"可靠工具"的设计目标
+
+### Decision 5: 无外部输入支持
+
+**决策：** 所有输入、参数和数据源都嵌入在Python脚本内部。不支持命令行参数和stdin输入。
+
+**理由：**
+- 简化skill的使用模型
+- 符合大模型生成脚本的使用模式（大模型知道所有参数）
+- 避免参数传递的复杂度和安全风险
+- 保持脚本的完整性和可移植性
+
+**替代方案考虑：**
+- 支持命令行参数：
+  - ❌ 增加skill复杂度（需要参数传递机制）
+  - ❌ 脚本可能依赖外部输入而不可移植
+  - ❌ 不符合"所有逻辑嵌入脚本"的设计目标
+
+### Decision 6: 通用任务适用性
+
+**决策：** skill不限制在特定领域，适用于任何Python可处理的任务。在文档中提供常见用例示例（数据分析、API交互、文件操作等），但不硬编码限制。
+
+**理由：**
+- 最大化skill的复用性
+- Python的适用范围很广，不应预先限制
+- 通过示例而非硬编码来引导使用
+
+**替代方案考虑：**
+- 针对特定领域（如只支持数据分析）：
+  - ❌ 限制了skill的通用性
+  - ❌ 可能需要多个类似skill覆盖不同场景
+  - ❌ 违反"通用工具"的设计目标
+
+## Risks / Trade-offs
+
+### Risk 1: uv依赖外部可用性
+
+**风险：** 技能依赖uv包管理器，如果系统未安装uv，skill无法工作。
+
+**缓解措施：**
+- 错误消息中提供清晰的uv安装链接
+- 在skill文档中明确说明uv是必需依赖
+- 提供uv安装指南（https://docs.astral.sh/uv/getting-started/installation/）
+
+### Risk 2: 临时文件
+
+**风险：** 临时文件存储在系统临时目录（/tmp 或 Windows Temp），磁盘空间占用。
+
+**缓解措施：**
+- 临时文件使用系统标准临时目录，系统会自动定期清理
+- 文件名包含时间戳，便于识别
+- 在失败时显示文件路径，方便用户手动删除
+
+### Risk 3: 依赖解析时间
+
+**风险：** 首次执行某个脚本时，uv需要下载和安装依赖，可能需要较长时间，影响用户体验。
+
+**缓解措施：**
+- 在文档中说明首次执行可能较慢
+- uv的依赖解析和安装速度很快（比传统pip快10-100倍）
+- 使用最新版本通常减少兼容性问题，加快解析速度
+
+### Risk 4: PyPI包可用性
+
+**风险：** 如果声明的依赖包在PyPI上不存在或名称错误，依赖解析会失败。
+
+**缓解措施：**
+- 严格错误处理模式会显示uv的完整错误输出
+- 大模型在编写脚本时已经知道依赖的包名
+- 保留失败的临时文件便于检查依赖声明
+
+### Risk 5: 大模型理解复杂度
+
+**风险：** PEP 723元数据格式对大模型来说可能不熟悉，可能生成不符合规范的脚本。
+
+**缓解措施：**
+- skill文档提供清晰的示例和模板
+- 严格错误处理会在语法或格式错误时立即停止并提示
+- 文档中说明常见的格式错误和修正方法
+
+## Migration Plan
+
+这是新skill的首次实现，不存在迁移问题。
+
+**部署步骤：**
+1. 创建skill目录：`skills/python-runner/`
+2. 创建skill文件：`skills/python-runner/SKILL.md`
+3. 编写skill内容（YAML元数据 + Markdown文档）
+4. 测试skill是否可以被正确加载和触发
+
+**回滚策略：**
+- 如有问题，直接删除`skills/python-runner/`目录即可
+- skill文件不影响系统或现有代码
+
+## Open Questions
+
+无。所有设计决策已在上述章节明确说明。