Metadata-Version: 2.4
Name: healpy-ai
Version: 0.1.0
Summary: AI 驱动的 Python 运行时错误自诊断与自动修复库
Author-email: Your Name <your.email@example.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=12.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Dynamic: license-file

# 🩺 HealPy-AI

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

---

## ✨ 核心特性

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

---

## 📸 终端诊断报告预览

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

```text
┌──────────────────────────────🩺 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 安装（抢先内测版）
在你的项目终端中运行：
```bash
pip install git+https://github.com/你的用户名/healpy.git
```

### 2. 本地开发调试安装
如果你想对本项目进行贡献，克隆后在项目根目录运行：
```bash
pip install -e .[dev]
```

---

## 🚀 快速上手

### 基础用法（错误自诊断）
只需将 `@heal()` 装饰器挂载在可能报错的函数上：

```python
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 可以在捕获异常时，为您提供参数微调或代码热修复，让执行失败的程序原地复活。

```python
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) # 输出: 张三
```

---

## 📂 项目结构描述

```text
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](LICENSE)** 协议开源。
