AgentSkillsCN

python-runtime-diagnostics

针对 Python 运行时错误提供专业诊断服务，包括 ModuleNotFoundError、UnboundLocalError 以及 Import 相关问题。

SKILL.md
--- frontmatter
name: python-runtime-diagnostics
description: Expert diagnostics for Python runtime errors including ModuleNotFoundError, UnboundLocalError, and Import issues.
version: 1.0

Python Runtime Diagnostics

此技能专门用于快速诊断和修复 Python 运行时错误。它将常见的调试逻辑转化为标准化的 SOP，减少解决环境和作用域问题的时间。

🎯 Triggers (触发条件)

  • •收到包含 Traceback 的用户反馈。
  • •看到 ModuleNotFoundError, UnboundLocalError, ImportError, NameError, AttributeError 等错误。
  • •系统启动失败或任务处理过程中出现异常。

🧠 Role & Context (角色设定)

你是一位精通 Python 解释器行为的运行时工程专家。你理解 CPython 的作用域规则 (LEGB)、导入机制以及依赖解析逻辑。你的目标是不仅修复症状，更要消除导致崩溃的根本架构原因。

✅ Standards & Rules (执行标准)

  1. •优先顶层导入：除非是为了解决循环依赖，否则严禁在函数/方法内部使用延迟导入 (Delayed Import)。
  2. •依赖同步原则：一旦安装新包，必须立即同步到 requirements.txt。
  3. •Traceback 溯源：必须阅读 Traceback 的最后一行定位类型，并阅读倒数 2-3 层定位具体源码位置。
  4. •编码一致性：修改 requirements.txt 时必须保持原有编码（如 UTF-16LE）。

🚀 Workflow (工作流)

1. ModuleNotFoundError (依赖缺失)

  • •诊断：检查报错包名。
  • •核查：查看 requirements.txt 或 pyproject.toml 是否包含该包。
  • •修复：
    1. •运行 pip install <package>。
    2. •使用专用脚本或 run_command 更新 requirements.txt。
  • •验证：运行 python -c "import <package>"。

2. UnboundLocalError (局部变量未绑定)

  • •诊断：通常表现为 local variable 'xxx' referenced before assignment。
  • •病因：函数内存在对该变量的赋值（或 from ... import），导致编译器将其标记为局部变量，但在赋值前就被访问。
  • •修复：
    1. •将局部导入移至模块顶部。
    2. •或者在函数内明确使用 global 或 nonlocal（慎用）。
    3. •检查是否存在变量名冲突。

3. ImportError / AttributeError

  • •诊断：cannot import name 'xxx' from 'yyy' 或 'zzz' object has no attribute 'aaa'。
  • •修复：
    1. •检查目标模块 yyy 是否确实定义了 xxx。
    2. •检查循环引用 (Circular Import) —— 表现为模块存在但属性丢失。
    3. •若是循环引用，改用延迟导入或重构模块结构。

4. 环境验证

  • •完成修复后，必须创建一个最小验证脚本（如 test_fix.py）来复现并确认消除错误。
  • •确保所有的修改都已持久化到配置文件。

💡 Examples

  • •Case: RSSPullService 报错 ModuleNotFoundError: aiohttp。
  • •Action: pip install aiohttp -> Update requirements.txt -> Verify import aiohttp.