# OpenWebView

**Repository Path**: CiChenMan/OpenWebView

## Basic Information

- **Project Name**: OpenWebView
- **Description**: 基于 `pywebview` 的浏览器容器，提供全面的窗口管理功能，js桥接api，资源管理器等功能。非常适合网页打包 `window` 平台的exe程序，让网页或AI拥有操作本地系统的能力。

- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI, exe, Python

## README

# OpenWebView

<div align="center">
  <table style="border: 2px solid #6366f1; border-radius: 16px; padding: 20px 32px; background: linear-gradient(135deg, #1e1b4b 0%, #312e81 50%, #3730a3 100%); box-shadow: 0 8px 32px rgba(99, 102, 241, 0.25); margin: 10px 0 24px 0;">
    <tr>
      <td align="center">
        <p style="margin: 0 0 6px 0; font-size: 13px; color: #a5b4fc; letter-spacing: 2px; text-transform: uppercase;">👤 作者</p>
        <p style="margin: 0 0 12px 0; font-size: 20px; font-weight: 700; color: #e0e7ff;">CiChenMan</p>
        <table style="margin: 0 auto; border: none;">
          <tr>
            <td style="padding: 0 12px; border: none;">
              <div style="background: rgba(255,255,255,0.08); border-radius: 10px; padding: 10px 18px; text-align: center; min-width: 110px; border: 1px solid rgba(255,255,255,0.1);">
                <span style="font-size: 18px;">🐧</span><br>
                <span style="font-size: 11px; color: #a5b4fc;">QQ</span><br>
                <span style="font-size: 14px; color: #c7d2fe; font-weight: 600;">1570442495</span>
              </div>
            </td>
            <td style="padding: 0 12px; border: none;">
              <div style="background: rgba(255,255,255,0.08); border-radius: 10px; padding: 10px 18px; text-align: center; min-width: 110px; border: 1px solid rgba(255,255,255,0.1);">
                <span style="font-size: 18px;">💬</span><br>
                <span style="font-size: 11px; color: #a5b4fc;">微信</span><br>
                <span style="font-size: 14px; color: #c7d2fe; font-weight: 600;">CiChenMan</span>
              </div>
            </td>
            <td style="padding: 0 12px; border: none;">
              <div style="background: rgba(255,255,255,0.08); border-radius: 10px; padding: 10px 18px; text-align: center; min-width: 110px; border: 1px solid rgba(255,255,255,0.1);">
                <span style="font-size: 18px;">🎵</span><br>
                <span style="font-size: 11px; color: #a5b4fc;">抖音</span><br>
                <span style="font-size: 14px; color: #c7d2fe; font-weight: 600;">CiChenMan</span>
              </div>
            </td>
          </tr>
        </table>
      </td>
    </tr>
  </table>
</div>

基于 `pywebview` 的浏览器容器，提供全面的窗口管理功能、JS 桥接 API、文件资源管理器、命令行工具和交互式 Shell 等功能。非常适合将网页打包为 Windows 平台的 EXE 程序，让网页与 AI 模型拥有操作本地系统的能力。

---

## 功能特性

### 窗口管理功能
提供完整的窗口控制能力，包括最小化、最大化、还原、移动、置顶、全屏切换等操作。

### 文件资源管理器
提供文件资源管理功能，便于网页或 AI 模型操作本地系统文件，包括目录选择、文件创建/删除/复制/移动、文件读取/写入等。

### 命令行工具
提供命令行执行功能，使用 PowerShell 执行系统命令，让网页或 AI 模型能够操作本地系统。

### 交互式 Shell
提供持久化的交互式终端会话，支持实时输入输出流式交互，适合长时间运行的 CLI 程序（如编译、调试、AI 对话等）。支持会话创建、读写、停止、重启、销毁、列表查询等完整生命周期管理。

### JS 桥接 API
将所有内置功能暴露到网页 JS 环境中，支持 Promise 异步调用。具体 API 文档请参阅 [API.md](API.md)。

---

## 安装依赖

```bash
pip install pywebview
```

> **注意**：Windows 系统需确保已安装 [WebView2 运行时](https://developer.microsoft.com/microsoft-edge/webview2/)。

---

## 启动参数

```bash
python main.py [选项] [URL]
```

### 位置参数

| 参数 | 说明 |
|------|------|
| `URL` | 初始加载的 URL（也可通过 `--url-arg` 指定） |

### 可选参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--title` | 字符串 | `"OpenWebView"` | 窗口标题 |
| `--url-arg` | 字符串 | — | 初始加载的 URL（优先于位置参数） |
| `--debug` | 布尔 | `true` | 是否开启 debug 模式，开启后可通过右键菜单手动打开 DevTools |
| `--frameless` | 布尔 | `true` | 是否使用无边框窗口 |
| `--width` | 整数 | `1200` | 窗口宽度（像素） |
| `--height` | 整数 | `780` | 窗口高度（像素） |
| `--resizable` | 布尔 | `true` | 是否允许拖拽调整窗口大小 |
| `--bg-color` | 字符串 | `"#1e1e1e"` | 窗口背景色（仅支持 `#RRGGBB` 十六进制格式） |
| `--transparent` | 布尔 | `false` | 是否启用窗口透明（开启后窗口背景透明，页面内容可控制自身透明度） |

> **注意**：`--transparent true` 会自动强制 `frameless=True` 并关闭窗口阴影。页面中需使用 CSS `background: transparent` 或 `rgba()` 来控制元素透明效果。

布尔参数可接受：`true` / `false`、`1` / `0`、`yes` / `no`

---

## 使用示例

```bash
# 默认启动（加载 demo.html）
python main.py

# 指定 URL
python main.py https://example.com

# 自定义标题和尺寸
python main.py --title "我的应用" --width 1600 --height 900

# 完整参数示例
python main.py \
  --title "浏览器" \
  --url-arg "https://example.com" \
  --debug true \
  --frameless true \
  --width 1920 \
  --height 1080 \
  --resizable true

# 有边框、禁止调整大小、关闭 debug
python main.py --frameless false --resizable false --debug false

# 白色背景
python main.py --bg-color "#ffffff"

# 黑色背景
python main.py --bg-color "#000000"

# 透明窗口（页面内容可控制自身透明度）
python main.py --transparent true
```

---

## 环境变量

| 变量 | 说明 |
|------|------|
| `OPENWEBVIEW_URL` | 设置默认初始 URL（优先级低于命令行参数） |

---

## 数据持久化

程序会在当前目录下创建 `.openwebview_data` 文件夹，用于存储 cookies、localStorage 等数据。

---

## 项目结构

```
OpenWebView/
├── main.py              # 主程序入口
├── lib/                 # 核心库
│   ├── __init__.py      # 包初始化
│   ├── api.py           # 窗口管理 API（继承所有 Mixin）
│   ├── windows.py       # 窗口注册表
│   ├── win32_helpers.py # Win32 平台辅助函数
│   └── mixins/          # API 功能模块
│       ├── __init__.py
│       ├── window_control.py     # 窗口控制（最小化、最大化、置顶、全屏等）
│       ├── clipboard.py          # 剪贴板操作
│       ├── navigation.py         # 页面导航（刷新、后退、前进）
│       ├── window_lifecycle.py   # 窗口生命周期（创建、销毁、列表、状态）
│       ├── js_execution.py       # JavaScript 执行
│       ├── command.py            # 命令执行
│       ├── file_manager.py       # 文件管理
│       └── interactive_shell.py  # 交互式 Shell
├── docs/                # 文档
│   ├── mixins/          # 各 Mixin 模块详细文档（Python 端）
│   │   ├── __init__.md
│   │   ├── clipboard.md
│   │   ├── command.md
│   │   ├── file_manager.md
│   │   ├── interactive_shell.md
│   │   ├── js_execution.md
│   │   ├── navigation.md
│   │   ├── window_control.md
│   │   └── window_lifecycle.md
│   └── jsapi/           # JS 桥接 API 文档（前端调用）
│       ├── quickstart.md           # 快速开始
│       ├── window_control.md       # 窗口控制
│       ├── window_state.md         # 窗口状态
│       ├── navigation.md           # 导航
│       ├── window_lifecycle.md     # 多窗口管理
│       ├── js_execution.md         # JS 执行
│       ├── command.md              # 命令行执行
│       ├── file_manager.md         # 文件资源管理
│       └── interactive_shell.md    # 交互式 Shell
├── public/              # 公共资源
│   ├── demo.html        # 功能演示页面
│   ├── webshell.html    # 交互式 Shell 演示页面
│   ├── chat-ai.ico      # 应用图标 (ICO)
│   ├── chat-ai.png      # 应用图标 (PNG)
│   └── ChatAI-Agent.lnk # 快捷方式
├── API.md               # JS 桥接 API 索引目录
├── LICENSE              # 许可证文件
└── README.md            # 项目说明文档
```

---

## 许可证

本项目基于 MIT 许可证开源。详细信息请参阅 [LICENSE](LICENSE) 文件。