Metadata-Version: 2.4
Name: wtsh
Version: 26.5.30
Summary: wtsh shell v26
Author-email: wazzge <2334498769@qq.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cmd2
Dynamic: license-file

# wtsh - 基于cmd2的插件化交互式命令行Shell

wtsh 是一个基于 Python cmd2 库开发的交互式命令行 Shell，提供了基本的文件系统操作和容器环境检测功能。

## 托管仓库
- [Gitee](https://gitee.com/wazzge/wtsh)

## 功能特性

- **交互式命令行界面**：基于 cmd2 框架，支持命令自动补全和历史记录
- **文件系统操作**：支持 ls、cat、cd、clear 等基本命令
- **容器环境检测**：自动识别 Docker、Podman、LXC 等容器运行时环境
- **彩色提示符**：显示用户名、当前目录和操作系统平台信息

---

## 该项目的功能

### 核心功能

1. **交互式命令行 Shell**
   - 提供用户友好的命令行交互界面
   - 支持命令自动补全和历史记录
   - 彩色提示符显示用户名、当前目录和操作系统平台

2. **文件系统操作**
   - `ls` - 列出当前目录下的文件和文件夹
   - `cat` - 显示指定文件的内容
   - `cd` - 切换工作目录
   - `clear` - 清除终端屏幕内容

3. **容器环境检测**
   - `whichcontainer` - 检测当前是否运行在容器环境中
   - 支持检测的容器类型：Docker、Podman、LXC、Host
   - 显示容器运行时和容器名称

4. **系统信息管理**
   - `aboutus` - 显示 wtsh 版本和系统详细信息
   - `restore_prompt` - 还原提示符为默认样式
   - 虚拟环境检测（内部功能）

5. **特殊功能**
   - `dexec` - 在 distrobox 容器内执行宿主机命令
   - 插件系统支持
   - Python 交互式命令支持

### 插件系统

- 基于 Python `entry_points` 机制的插件发现和加载
- 支持动态加载 `wtsh.plugins` 组下的所有插件
- 支持 cmd2.commandset 模式的插件
- 插件在启动时自动加载并显示加载状态

---

## 使用的cmd2模块的功能

wtsh 项目充分利用了 cmd2 库的强大功能，具体包括：

### 核心框架功能

1. **Cmd 基类继承**
   - 通过继承 `cmd2.Cmd` 类创建交互式命令行应用
   - 提供完整的命令解析和执行框架

2. **命令自动加载**
   - `auto_load_commands=True` - 自动加载所有命令方法
   - 支持装饰器模式定义命令

3. **Python 交互支持**
   - `include_py=True` - 集成 Python 交互式命令
   - 允许在 Shell 中直接执行 Python 代码

### 命令管理

4. **命令分类**
   - `@with_default_category` 装饰器 - 为命令分组
   - 支持按类别组织和管理命令

5. **命令定义**
   - `do_*` 方法命名约定 - 自动注册为命令
   - 命令文档字符串自动生成帮助信息

6. **输出管理**
   - `poutput()` - 标准输出方法
   - `perror()` - 错误输出方法
   - 统一的输出接口便于测试和重定向

### 交互功能

7. **命令循环**
   - `cmdloop()` - 启动命令行交互循环
   - 处理用户输入和命令执行

8. **空行处理**
   - `emptyline()` - 自定义空行行为
   - 避免重复执行上一条命令

9. **提示符自定义**
   - `self.prompt` - 自定义提示符样式
   - 支持 ANSI 颜色代码和动态内容

### 插件系统

10. **CommandSet 支持**
    - 支持 cmd2.commandset 模式的插件
    - 允许通过插件扩展命令集
    - 模块化的命令组织方式

### 其他特性

11. **参数解析**
    - 内置参数解析和验证
    - 支持复杂命令参数

12. **历史记录**
    - 命令历史记录功能
    - 支持历史命令导航

13. **自动补全**
    - 命令和参数自动补全
    - 提升用户体验

---

## 安装要求

- Python 3.10+ (Windows7不支持)
- cmd2 库


## 快速开始

### 运行方式

```bash
python wtsh.py
```
如果安装后运行：
```bash
wtsh
```


启动后会显示欢迎信息：

```
Welcome to the wtsh shell!wtsh version 26.5.17
username@/current/directory:platform>
```

## 命令列表

### 基础命令

| 命令 | 描述 | 示例 |
|------|------|------|
| `ls` | 列出当前目录下的文件和文件夹 | `ls` |
| `cat <file>` | 显示文件内容 | `cat README.md` |
| `cd <dir>` | 切换目录 | `cd /home/user` |
| `clear` | 清屏 | `clear` |
| `exit` | 退出 Shell | `exit` |

### 系统信息

| 命令 | 描述 |
|------|------|
| `aboutus` | 显示 wtsh 版本和系统信息 |
| `whichcontainer` | 检测当前是否运行在容器环境中 |
| `restore_prompt` | 还原提示符为默认样式 |

## 命令详解

### ls

列出当前目录下的所有文件和目录：

```bash
username@/home:linux> ls
Documents
Downloads
Desktop
```

### cat

显示指定文件的内容：

```bash
username@/home:linux> cat example.txt
Hello, wtsh!
```

### cd

切换到指定目录：

```bash
username@/home:linux> cd Documents
username@/home/Documents:linux>
```

### clear

清除终端屏幕内容。

### exit

退出 wtsh Shell，返回系统命令行。

### aboutus

显示 wtsh 的版本信息和运行时平台：

```bash
username@/home:linux> aboutus
wtsh version: 26.5.17
wtsh plugin protocol version: 7.2.0
wtsh plugin protocol name: wtsh.plugins
wtsh plugin protocol platform: entry_points
wtsh main runtime platform(OS platform): linux
supported plugin types: entrypoints+cmd2.commandset
```

### whichcontainer

检测当前运行环境是否为容器，并显示容器运行时和名称：

```bash
username@/home:linux> whichcontainer
docker my-container
```

支持检测的容器类型：
- Docker
- Podman
- LXC
- Host（非容器环境）

### restore_prompt

将提示符恢复为默认样式，移除容器信息显示。

## 提示符说明

wtsh 的提示符包含以下信息（带颜色）：

```
\033[32m{username}\033[0m@\033[34m{current_dir}\033[0m:\033[33m{platform}\033[0m>
```

- **绿色**：用户名
- **蓝色**：当前工作目录
- **黄色**：操作系统平台



## 插件系统

wtsh 支持通过插件机制扩展功能，采用 Python `entry_points` 作为插件发现机制。

### 插件机制

wtsh 在启动时会自动扫描 `wtsh.plugins` 组下的所有 entry points，并动态加载：

```python
for ep in entry_points(group="wtsh.plugins"):
    ep.load()
    print(f'Loaded plugin {ep.name}')
```

### 插件协议信息

- **插件协议名称**：`wtsh.plugins`
- **插件协议版本**：7.2.0
- **插件平台**：`entry_points`
- **支持的插件类型**：`entrypoints+cmd2.commandset`

### 插件加载

插件会在 wtsh 启动时自动加载，加载成功后会显示：

```
Loaded plugin plugin_name
```

如果没有找到插件或加载失败，会显示相应的提示信息。

## 支持的平台

wtsh 可以在以下操作系统上运行：

- Linux
- Windows
- macOS
- KaihongOS （只支持在兼容层中安装，不支持直接在KaihongOS上运行，因为KaihongOS没有用户态python环境。之后KaihongOS会逐步开放用户可达的docker）

## 许可证

Apache License 2.0

## 版本历史

- **26.5.17**：当前版本，优化whl打包、docker镜像和容器检测功能，容器检测功能移除“自动附加到提示符”以防止信息泄露
- **26.5.0**：初始版本，包含基础文件操作和容器检测功能
