# python-tk-webview-socket-client

**Repository Path**: cps-cli-template/python-tk-webview-socket-client

## Basic Information

- **Project Name**: python-tk-webview-socket-client
- **Description**: python-tk-webview-socket-client
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Python TK WebView Socket Client

这是一个基于 Python 的模块化应用框架，采用消息总线架构，支持 TK UI 和 WebView 集成，通过 Socket 实现模块间通信。系统具有高度的可扩展性和可靠性，适用于构建复杂的桌面应用程序。

## 系统功能

### 核心功能

1. **消息总线系统**
   - 基于 Socket 的模块间通信
   - 支持消息路由、广播
   - 模块注册与管理
   - 心跳机制确保连接稳定性

2. **模块化架构**
   - 统一的模块基类 `ModuleBase`
   - 生命周期管理（启动、运行、停止）
   - 消息处理机制
   - 可扩展的模块系统

3. **模块管理**
   - 自动拉起指定模块
   - 单实例/多实例控制
   - 模块自动重启功能
   - 模块健康监控

4. **UI 集成**
   - Tk 图形界面
   - 消息发送功能
   - 截图请求功能

5. **业务模块**
   - UI 模块：提供用户界面
   - 截图模块：处理截图请求
   - OCR 模块：提供文字识别功能

## 核心目录架构

```
src/
├── core/              # 核心模块
│   ├── bus_server.py  # 消息总线中心
│   ├── launcher.py    # 系统总入口
│   ├── module_manager.py  # 模块管理器
│   ├── protocol.py    # 消息协议
│   └── supervisor.py  # 主控层
└── module/            # 模块系统
    ├── base/          # 基础模块
    │   └── module_base.py  # 模块基类
    ├── config/        # 配置模块
    ├── ocr_module/     # OCR 模块
    │   ├── __init__.py
    │   └── main.py
    ├── screenshot_module/  # 截图模块
    │   ├── __init__.py
    │   └── main.py
    └── ui_module/     # UI 模块
        ├── __init__.py
        └── main.py
```

## 主要文件职责

### 核心文件

1. **launcher.py**
   - 系统总入口
   - 启动 Supervisor 并运行系统
   - 提供简单的命令行接口

2. **supervisor.py**
   - 主控层，负责系统级生命周期管理
   - 协调 BusServer 和 ModuleManager
   - 处理系统启动、运行和停止

3. **bus_server.py**
   - 消息总线中心
   - 处理模块注册和注销
   - 负责消息路由和广播
   - 管理模块间的通信

4. **module_manager.py**
   - 模块管理器
   - 负责模块的注册、配置和管理
   - 实现模块的启动、停止和监控
   - 支持单实例和多实例模块
   - 提供模块状态查询功能

5. **protocol.py**
   - 消息协议层
   - 定义统一的消息格式
   - 实现消息的编码和解码
   - 处理消息边界

### 模块文件

1. **module/base/module_base.py**
   - 模块基类
   - 提供统一的模块行为规范
   - 实现生命周期管理
   - 提供消息收发机制
   - 实现心跳机制

2. **module/ui_module/main.py**
   - UI 模块
   - 实现 Tk 图形界面
   - 提供消息发送功能
   - 处理截图请求

3. **module/screenshot_module/main.py**
   - 截图模块
   - 处理截图请求
   - 返回截图结果

4. **module/ocr_module/main.py**
   - OCR 模块
   - 处理文字识别请求
   - 返回识别结果

## 使用规范

### 系统启动

```bash
# 安装依赖
pdm install

# 启动系统
pdm run python src/core/launcher.py
```

### 模块开发

1. **创建模块**
   - 在 `src/module/` 目录下创建新的模块目录
   - 编写 `main.py` 文件，继承 `ModuleBase` 类
   - 实现必要的方法：`on_start`、`handle_message` 等

2. **注册模块**
   - 在 `core/module_manager.py` 文件中注册新模块
   - 配置模块的单例/多例属性、自动重启等

3. **消息格式**
   - 发送消息：使用 `self.send()` 方法
   - 回复消息：使用 `self.reply()` 方法
   - 消息结构遵循统一格式

### 模块通信

- 模块间只通过 Bus 进行通信
- 所有消息使用统一的格式
- 支持点对点通信和广播

### 配置管理

- 模块配置在 `module_manager.py` 中定义
- 支持设置模块的单例/多例属性
- 支持配置自动重启功能

## 模块开发指南

### 基本模块结构

```python
# src/module/example_module/main.py

from module.base.module_base import ModuleBase


class ExampleModule(ModuleBase):
    def __init__(self):
        super().__init__(module_name="example_module")

    def on_start(self):
        self.log("Example 模块启动")

    def handle_message(self, msg):
        super().handle_message(msg)
        
        action = msg.get("action")
        if action == "example_action":
            # 处理动作
            self.reply(msg, "example_result", {"status": "success", "data": "处理结果"})


def main():
    module = ExampleModule()
    module.run_forever()


if __name__ == "__main__":
    main()
```

### 消息处理

- 重写 `handle_message` 方法处理接收到的消息
- 使用 `self.send()` 发送消息给其他模块
- 使用 `self.reply()` 回复消息

### 生命周期管理

- `on_start()`：模块启动时调用
- `on_stop()`：模块停止时调用
- `loop_once()`：主循环单步执行（可选）

## 测试

### 运行测试

```bash
# 运行所有测试
pdm run python -m unittest discover tests

# 运行特定测试
pdm run python -m unittest tests/test_module_base.py
```

### 测试用例

- `test_module_base.py`：测试模块基类的功能
- 测试模块启动和停止
- 测试消息发送和接收
- 测试心跳机制

## 优势

1. **模块化设计**：系统采用高度模块化的设计，易于扩展和维护
2. **消息总线**：基于 Socket 的消息总线，实现模块间的解耦
3. **自动管理**：模块自动重启，确保系统稳定性
4. **灵活配置**：支持单实例和多实例模块
5. **统一规范**：所有模块遵循统一的开发规范

## 应用场景

- 复杂的桌面应用程序
- 需要多个功能模块协作的系统
- 对稳定性和可靠性要求较高的应用
- 需要图形界面的 Python 应用

## 许可证

MIT License

## 作者

Capsion <373704015@qq.com>