9.7 KiB
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/uv-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/uv-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
- Linux/macOS:
大模型使用流程：
- 调用辅助脚本获取临时脚本文件路径（使用相对路径
./script/get_temp_path.py，相对于SKILL.md所在目录）temp_file_path=$(uv run ./script/get_temp_path.py) - 在返回的脚本文件路径中直接写入PEP 723脚本内容：
# 使用大模型的Write工具 with open(temp_file_path, 'w') as f: f.write(script_content) - 使用
uv run执行脚本：uv run $temp_file_path - 系统自动清理临时文件，无需手动管理
替代方案考虑：
- 在辅助脚本中导出函数供导入：
- ❌ 需要大模型导入模块并调用函数，增加了复杂度
- ❌ 辅助脚本需要更多代码（函数定义、文档等）
- ❌ 不符合"简单直接"的设计原则
- 在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的首次实现，不存在迁移问题。
部署步骤：
- 创建skill目录：
skills/uv-python-runner/ - 创建skill文件：
skills/uv-python-runner/SKILL.md - 编写skill内容（YAML元数据 + Markdown文档）
- 测试skill是否可以被正确加载和触发
回滚策略：
- 如有问题，直接删除
skills/uv-python-runner/目录即可 - skill文件不影响系统或现有代码
Open Questions
无。所有设计决策已在上述章节明确说明。