previewra 0.1.0

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

Previewra (pvr)

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

pip install previewra

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

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

---

Quick Start

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

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

---

Commands

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 可临时切换语言：

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）：

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

或通过环境变量：

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

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

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

---

License

MIT