Metadata-Version: 2.4
Name: wtsh
Version: 26.8.1
Summary: wtsh shell v26
Author-email: wazzge <wazzge920@163.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 等容器运行时环境
- **外部提示符支持**：支持接入 Oh-My-Posh 等第三方提示符工具
- **底栏信息展示**：显示用户、路径、解释器等信息

---

## 核心功能

1. **交互式命令行 Shell**
   - 提供用户友好的命令行交互界面
   - 支持命令自动补全和历史记录
   - 彩色提示符显示

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

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

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

5. **特殊功能**
   - `dexec` - 在 distrobox 容器内执行宿主机命令
   - 环境变量管理（export、unset、pathrm）
   - 初始化文件支持（.wtshrc）
   - 插件系统支持
   - Python 交互式命令支持
   - **Oh-My-Posh 提示符接入**

---

## 安装要求

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

## 快速开始

### 运行方式

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

启动后会显示欢迎信息：

```
Python 3.11.2 
Welcome to the wtsh shell! wtsh version 26.7.21. 
==>>
```

如果配置了 Oh-My-Posh 作为提示符后端，效果如下：

```
Python 3.11.2 
Welcome to the wtsh shell! wtsh version 26.7.21. 
Loaded rc file: /home/user/.wtshrc
user@hostname ~/projects/wtsh
❯
```

## 命令列表

### 基础命令

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

### 系统信息

| 命令 | 描述 |
|------|------|
| `aboutus` | 显示 wtsh 版本和系统信息 |
| `lsplugins` | 列出所有已加载的插件和命令集 |
| `see_blacklist` | 显示命令执行黑名单 |
| `restore_prompt` | 还原提示符为默认样式 |

### Python 包管理

| 命令 | 描述 |
|------|------|
| `pipw list` | 列出已安装的 Python 包 |
| `pipw install <pkg>` | 安装 Python 包 |
| `pipw remove <pkg>` | 卸载 Python 包 |
| `pipw runtool <tool>` | 运行已安装的命令行工具 |

### 环境变量管理

| 命令 | 描述 |
|------|------|
| `export` | 显示或设置环境变量（支持追加 `+=` 和前置 `=:`） |
| `unset` | 删除环境变量（关键变量如 PATH 受保护） |
| `pathrm` | 从 PATH 中移除指定路径片段 |

### 虚拟环境管理

> **重要声明**：wtsh **彻底抛弃 venv 的 activate/deactivate 体系**，不允许激活虚拟环境。这是为了教育用户正确的运维意识——直接指定解释器路径是更清晰、更可控的方式。`py_venv_activate` 和 `py_venv_exit` 命令已移除。

### 推荐做法

#### 1. 向 wtsh 所在环境安装包
```bash
# 安装包到当前环境
pipw install requests

# 从当前环境卸载包
pipw remove requests
```

#### 2. 运行 wtsh 所在环境中的控制台应用
使用 `pipw runtool` 命令运行安装在当前环境中的命令行工具：
```bash
# 运行 black 代码格式化工具
pipw runtool black --check .

# 运行 pytest 测试框架
pipw runtool pytest tests/

# 运行 flake8 代码检查工具
pipw runtool flake8 src/
```

#### 3. 执行其他 Python 文件或使用其他解释器
- **方式一（推荐）**：使用 `!` 前缀直接指定解释器路径
  ```bash
  # 使用 venv 解释器执行脚本
  !/path/to/.venv/bin/python3 script.py arg1 arg2
  
  # 使用 venv 的 pip 安装包
  !/path/to/.venv/bin/pip install package
  
  # 运行 venv 中的命令行工具
  !/path/to/.venv/bin/black --check .
  ```

- **方式二**：使用 `runpy` 命令（需先设置子进程解释器）
  ```bash
  # 设置子进程解释器
  set subprocess_interpreter "/path/to/.venv/bin/python3"
  
  # 使用 runpy 执行脚本
  runpy script.py arg1 arg2
  ```

### 防御手段

为防止通过环境变量绕过虚拟环境隔离，`export`、`unset`、`pathrm` 三件套已拦截屏蔽了 venv 激活所需的环境变量修改：

- **拦截 `VIRTUAL_ENV` 变量设置**：禁止设置或修改该变量
- **保护关键路径**：防止通过修改 `PATH` 注入 venv 的 bin 目录
- **保护 `PYTHONHOME`、`PYTHONPATH`**：防止劫持 Python 模块搜索路径

这些措施确保用户无法通过环境变量方式"激活"虚拟环境，强制使用显式指定解释器路径的正确方式。

## 命令详解

### ls

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

```bash
==>> ls
Documents
Downloads
Desktop
```

### cat

显示指定文件的内容：

```bash
==>> cat example.txt
Hello, wtsh!
```

### cd

切换到指定目录：

```bash
==>> cd Documents
==>> 
```

### clear

清除终端屏幕内容。

### exit

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

### aboutus

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

```bash
==>> aboutus
wtsh version: 26.7.21
wtsh plugin protocol version: 7.2.0
wtsh plugin protocol platform: entry_points
wtsh plugin entry_points: wtsh.plugins
wtsh main runtime platform(OS platform): linux
supported plugin types: entrypoints+cmd2.commandset --by cmd2
cmd2 version: 4.0.0
```

### lsplugins

列出所有已加载的插件和命令集：

```bash
==>> lsplugins
plugin_name (entry_point)
```

### see_blacklist

显示命令执行黑名单（这些命令被禁止执行）：

```bash
==>> see_blacklist
dd
format
```

### restore_prompt

将提示符恢复为默认样式。

### pipw

Python 包管理命令，支持多个子命令：

```bash
# 列出已安装的包
pipw list

# 安装包
pipw install requests

# 卸载包
pipw remove requests

# 运行命令行工具
pipw runtool black
```

### export

显示或设置环境变量：

```bash
# 显示所有环境变量
export

# 显示指定变量
export PATH

# 设置变量
export MYVAR=hello

# 设置带空格的值（需要引号）
export MYVAR="hello world"

# 追加到变量（适用于 PATH 等）
export PATH+=/new/bin

# 前置到变量开头
export PATH=:/priority/bin
```

### unset

删除环境变量（关键变量如 PATH、HOME 等受保护，无法删除）：

```bash
unset MYVAR
```

### pathrm

从 PATH 中移除指定路径片段：

```bash
pathrm /usr/local/bin
```

## 初始化文件

wtsh 支持在用户目录下使用 `.wtshrc` 文件作为初始化脚本。启动时会自动执行该文件中的命令。

初始化文件位置：`~/.wtshrc`

如果初始化文件加载成功，会显示：
```
Loaded rc file: /home/user/.wtshrc
```

如果文件不存在，会显示警告信息。

## Oh-My-Posh 提示符接入

wtsh 支持接入 Oh-My-Posh 等第三方提示符工具，提供更丰富的提示符样式。

### 配置方法

```bash
# 设置 Oh-My-Posh 作为主提示符
set main_prompt_provider 'oh-my-posh print primary'

# 刷新提示符
restore_prompt
```

### 效果预览

**启用 Oh-My-Posh 后：**

```
┌─────────────────────────────────────────────────────────────────┐
│ user@hostname ~/projects/wtsh                                   │
│ ❯                                                               │
│                            subprocess-interpreter=[ python3.11 ] │
└─────────────────────────────────────────────────────────────────┘
```

**原生提示符模式：**

```
┌─────────────────────────────────────────────────────────────────┐
│ ==>> ls                                                         │
│ Documents  Downloads  Desktop                                   │
│                            subprocess-interpreter=[ python3.11 ] │
└─────────────────────────────────────────────────────────────────┘
```

### 安全限制

为防止命令注入攻击，`main_prompt_provider` 配置项禁止包含以下危险字符：
- `;` - 命令分隔符
- `&`, `|` - 管道符
- `>`, `<` - 重定向符
- `` ` `` - 反引号命令执行
- `$(` - 子shell命令执行

### 底栏行为

- **原生提示符模式**：底栏显示完整信息（用户、路径、解释器）
- **Oh-My-Posh 模式**：底栏只显示解释器信息（用户和路径由 Oh-My-Posh 显示）

## 插件系统

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

### 插件机制

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

```python
for ep in entry_points(group="wtsh.plugins"):
    cls = ep.load()
    if inspect.isclass(cls) and issubclass(cls, cmd2.CommandSet):
        self.register_command_set(cls())
        print(f'Loaded plugin {ep.name}')
```

### 插件协议信息

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

### 插件开发

开发 wtsh 插件需要：

1. 创建一个继承自 `cmd2.CommandSet` 的类
2. 在 `pyproject.toml` 中注册 entry point：

```toml
[project.entry-points."wtsh.plugins"]
my_plugin = "my_package.my_module:MyCommandSet"
```

3. 实现自定义命令方法（使用 `@with_category` 装饰器分类）

### 插件加载

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

```
Loaded plugin plugin_name
```

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

### 插件管理命令

| 命令 | 描述 |
|------|------|
| `lsplugins` | 列出所有已加载的插件和命令集 |

### 安全限制

- 命令执行黑名单（`dd`、`format`）对插件命令同样生效
- 插件无法修改主程序的 `__BLACKLIST` 变量

## 支持的平台

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

- Linux
- Windows
- macOS
- KaihongOS （docker容器内运行）

## AI 辅助开发说明

坦白说，这个项目的代码有不少是我（人类）和 AI 一起写的。我负责想"要做什么"和"为什么这么做"，比如设计整体架构、定义项目理念、把关安全性；而 AI 则帮我把想法变成具体的代码实现，还能优化代码结构、写文档示例。

这种合作模式很高效：我抛出一个需求，AI 给出初步实现，我再审核、修改、打磨，最终形成可用的功能。但请放心，项目的核心思想、安全策略和关键决策都是我来把控的，AI 只是个给力的助手。

## 许可证

Apache License 2.0

## 版本历史

- **26.7.21**：新增 Oh-My-Posh 提示符接入支持；优化底栏显示逻辑，外部提示符模式下仅显示解释器信息；添加命令注入安全限制；移除废弃命令 `py_venv_activate`、`py_venv_exit` 和 `import_all_commandsets_from_an_independent_py`
- **26.7.18**：新增环境变量管理命令（export、unset、pathrm），支持环境变量的设置、追加、前置和删除；彻底抛弃 venv 的 activate/deactivate 体系；保护关键环境变量（PATH、HOME等）不被误删
- **26.6.28**：新增命令执行黑名单（__BLACKLIST），commandset不可修改；提供统一的插件接口类libwtsh_utils
- **26.6.18**：添加初步的底栏支持，主提示符精简，添加右提示符
- **26.5.30**：升级到cmd2-v4、新增虚拟环境管理功能、初始化文件支持（.wtshrc）、distrobox容器内执行宿主机命令（dexec）、优化清屏功能支持Windows、新增cmd2版本显示
- **26.5.17**：优化whl打包、docker镜像和容器检测功能，容器检测功能移除"自动附加到提示符"以防止信息泄露
- **26.5.0**：初始版本，包含基础文件操作和容器检测功能
