healpy-ai 0.1.0

AI 驱动的 Python 运行时错误自诊断与自动修复库

🩺 HealPy-AI

AI 驱动的 Python 运行时错误自诊断与自动修复库。
让晦涩的 Python Traceback 随风而去！HealPy 能在你的代码发生崩溃的瞬间，提供精准、优雅、直观的中文诊断报告，甚至在运行时帮你把代码“治愈”！

---

✨ 核心特性

• 🛡️ 无侵入接入：只需一个 @heal 装饰器，无缝守护你的核心业务函数。
• 📸 崩塌瞬间快照：自动抓取崩溃瞬间的最内层局部变量 (Locals) 数值、出错行代码及上下文，在控制台完美还原案发现场。
• 🤖 AI 与本地双诊断引擎：
  • 有网/有密钥：调用大模型，结合崩溃上下文和变量数据，生成量身定制的精准中文排查建议。
  • 无网/无密钥：平滑降级至精心设计的本地启发式诊断规则库，零成本秒级给出排查思路。
• 🛠️ 魔法自愈 (Auto-Patch)：
  • 交互式参数热修正：在终端直接手动微调崩溃时的传入参数并原地重试。
  • AI 代码热插拔 (AI Hot-Patching)：自动编译 AI 给出的一键修复代码块并动态重试，让报错程序无感起死回生！
• 🎨 美轮美奂的排版：基于 Rich 库精心调配的莫兰迪配色终端卡片，让 Debug 变成一种视觉享受。

---

📸 终端诊断报告预览

当你的代码报错时，HealPy 会在终端呈现出如下精美绝伦的卡片（模拟输出效果）：

┌──────────────────────────────🩺 HealPy 运行时异常防御系统 ──────────────────────────────┐
│  HEALPY AI 诊断 🤖  捕获运行时异常: ZeroDivisionError                                  │
│  错误信息: division by zero                                                            │
└────────────────────────────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────📍 异常定位 ──────────────────────────────────────┐
│ 📍 出错文件: /workspace/project/sales.py                                               │
│ 🎯 崩溃函数: calculate_ratio()                                                          │
│ 🔢 出错行号: 第 12 行                                                                   │
└────────────────────────────────────────────────────────────────────────────────────────┘
┌───────────────────────────📝 现场源码上下文 (报错行已高亮) ───────────────────────────┐
│    9: def calculate_ratio(total_sales, count):                                         │
│   10:     """计算销售比率"""                                                           │
│   11:     ratio = total_sales / count                                                  │
│ > 12:     return ratio                                                                 │
│   13:                                                                                  │
└────────────────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────🔍 报错瞬间局部变量快照 (Locals Snapshot) ───────────────────────┐
│ 变量名 (Variable)    类型 (Type)   当前数值 (Value)                                     │
│ total_sales         int           150000                                               │
│ count               int           0                                                    │
└────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────💡 HealPy 智能诊断结论 ─────────────────────────────────┐
│ 💡 核心总结: 尝试除以零                                                                  │
│ 🧐 深度分析: 运行时传入的参数 count 值为 0，导致执行 total_sales / count 时发生物理崩溃。│
│ 🛠️ 修复建议: 建议在除法前增加安全校验：                                                  │
│              if count == 0:                                                            │
│                  return 0                                                              │
└────────────────────────────────────────────────────────────────────────────────────────┘

---

📦 安装指南

1. 直接从 GitHub 安装（抢先内测版）

在你的项目终端中运行：

pip install git+https://github.com/你的用户名/healpy.git

2. 本地开发调试安装

如果你想对本项目进行贡献，克隆后在项目根目录运行：

pip install -e .[dev]

---

🚀 快速上手

基础用法（错误自诊断）

只需将 @heal() 装饰器挂载在可能报错的函数上：

from healpy import heal

# 建议在环境变量中配置 HEALPY_API_KEY 或 GEMINI_API_KEY 接入 AI 引擎。
# 若未配置，将自动采用本地启发式规则诊断。
@heal()
def unstable_function(data, index):
    return data[index]

# 故意触发 IndexError，HealPy 会在终端打印美轮美奂的排版及中文排查建议！
unstable_function([10, 20], 5)

---

🔮 进阶魔法：开启自愈重试 (auto_patch)

启用 auto_patch=True 后，HealPy 可以在捕获异常时，为您提供参数微调或代码热修复，让执行失败的程序原地复活。

from healpy import heal

# 启用自动修补模式
@heal(auto_patch=True)
def query_user(user_db, user_id):
    return user_db[user_id]

database = {"user_01": "张三"}

# 故意传入一个不存在的 'user_99' 触发 KeyError
# HealPy 会自动识别崩溃，并在终端弹出询问：
# "❓ 您是否想手动修改传入参数并重新尝试运行？ (y/n)"
# 输入 'y' 后，您可以在终端中直接输入 'user_01'，程序会奇迹般地带回正确结果并继续前行！
result = query_user(database, "user_99")
print(result) # 输出: 张三

---

📂 项目结构描述

healpy/
├── pyproject.toml         # 现代项目打包配置
├── README.md              # 本文档
├── LICENSE                # MIT License
├── healpy/                # 源码目录
│   ├── __init__.py        # 暴露外部核心 API
│   ├── core.py            # @heal 核心装饰器与局部帧抓取
│   ├── diagnoser.py       # 本地与 AI 双轨道智能诊断模块
│   ├── formatter.py       # Rich 终端精美渲染器
│   └── patcher.py         # 交互式运行时自愈与代码热修复模块
└── tests/                 # 测试目录
    └── test_core.py       # 自动化单元测试用例

---

📜 开源协议

本项目采用 MIT License 协议开源。