Metadata-Version: 2.4
Name: previewra
Version: 0.1.0
Summary: AI-native Runtime OS Layer — instant preview for AI-coded projects
Author: previewra
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.104.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: watchdog>=3.0.0
Description-Content-Type: text/markdown

# Previewra (pvr)

[![GitHub Stars](https://img.shields.io/github/stars/wangjun3862/previewra?style=flat-square&logo=github)](https://github.com/wangjun3862/previewra/stargazers)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](https://github.com/wangjun3862/previewra/blob/main/LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10+-3776ab?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/previewra?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/previewra/)

**AI-native Runtime OS Layer — instant preview for AI-coded projects.**

AI 编写的代码往往缺少运行说明。Previewra 自动检测项目类型、安装依赖、启动服务，并通过 Web Dashboard 实时预览，让 AI 生成的项目开箱即用。

---

## Features

- **Zero-config launch** — 自动识别 FastAPI / Flask / React / Vite / 静态站 / Python 脚本
- **Auto install** — 自动执行 `pip install` 或 `npm install`
- **Real-time dashboard** — 内置 Web 面板，含服务状态、日志流、反向代理预览
- **AI Self-Fix** — 服务启动失败时，AI 自动检查并修正 previewra 自身的检测配置（不修改你的代码）
- **Doctor** — 诊断引擎，输出结构化故障报告
- **File watcher** — 文件变化后自动刷新服务
- **Session history** — 记录每次运行的会话，支持查询历史
- **Tri-language** — 简体中文 / 繁体中文 / English

---

## Installation

**要求：** Python ≥ 3.10

```bash
pip install previewra
```

开发模式安装（本地源码）：

```bash
git clone https://github.com/wangjun3862/previewra.git
cd previewra
pip install -e .
```

---

## Quick Start

```bash
# 进入你的项目目录，一键启动
pvr preview .
```

Previewra 会自动完成：检测 → 安装依赖 → 启动服务 → 打开 Dashboard → 浏览器预览。

---

## Commands

```bash
pvr preview <path>              # 检测 + 安装 + 启动 + 打开 Dashboard
pvr watch <path>                # 同上，并监听文件变化自动刷新
pvr status <path>               # 输出当前 RuntimeState JSON
pvr doctor <path>               # 诊断报告（加 --json 输出纯 JSON）
pvr stop <path>                 # 优雅停止所有服务
pvr refresh <path>              # 重新检测并热重启

pvr sessions list               # 列出历史会话
pvr sessions show <session_id>  # 查看某次会话详情

pvr config lang <locale>        # 设置语言（zh-CN / zh-TW / en）
pvr config ai set <preset> <api-key>  # 配置 AI 自检修复
```

全局选项 `--lang` 可临时切换语言：

```bash
pvr --lang en preview .
```

---

## Dashboard

服务启动后，Dashboard 自动在浏览器打开（默认 `http://localhost:18080`）。

| 区域 | 说明 |
|---|---|
| 服务标签页 | 多服务切换，实时状态徽章 |
| 指标行 | CPU / 内存 / Uptime / 端口 / 响应时间 |
| 预览 iframe | 通过内置反向代理展示你的应用 |
| 日志区 | WebSocket 实时日志流 |
| AI Self-Fix | 一键让 AI 修正 previewra 的检测失误 |

---

## AI Self-Fix

当服务状态为 **CRASHED** 或 **FAILED** 时，点击 Dashboard 的 **AI Self-Fix** 按钮：

1. AI 分析启动日志 + 项目配置文件（requirements.txt、package.json 等）
2. 判断是否为 previewra 自身的检测失误（错误的启动命令、端口、缺失 flag 等）
3. 若是 → 自动修正配置并热重启服务，**不修改你的任何代码**
4. 若根因在用户代码 → 在日志区提示"超出 previewra 的修复范围"，由开发者处理

配置 AI 提供商（支持 OpenAI / Kimi / DeepSeek / Qwen / Gemini / Anthropic）：

```bash
pvr config ai set openai sk-xxxx
pvr config ai set kimi <moonshot-api-key>
pvr config ai set deepseek <deepseek-api-key>
```

或通过环境变量：

```bash
export PVR_AI_API_KEY=sk-xxxx
export PVR_AI_BASE_URL=https://api.openai.com/v1
export PVR_AI_MODEL=gpt-4o-mini
```

---

## Supported Project Types

| 类型 | 检测条件 | 默认端口 |
|---|---|---|
| FastAPI | `.py` 文件含 `from fastapi` / `import fastapi` | 8000 |
| Flask | `.py` 文件含 `from flask` / `import flask` | 5000 |
| React (Vite) | `package.json` 含 `vite` 依赖 | 5173 |
| React (CRA) | `package.json` 含 `react` 依赖 | 3000 |
| Python Script | 存在 `main.py` / `app.py` | — |
| Static | 存在 `index.html` | 8080 |

---

## Language Support

| 语言 | locale |
|---|---|
| English | `en` |
| 简体中文 | `zh-CN` |
| 繁体中文 | `zh-TW` |

```bash
pvr config lang zh-CN   # 持久化设置
pvr --lang en preview . # 单次覆盖
```

Dashboard 语言通过右上角下拉框切换，实时生效。

---

## License

MIT
