# Windows by Linux Shell

**Repository Path**: legend0/wsh

## Basic Information

- **Project Name**: Windows by Linux Shell
- **Description**: WSH 是一个用 Python 实现的 Windows 命令行替代工具，核心功能是将 Linux 风格的命令翻译为 Windows 命令并执行，同时提供现代化的终端交互体验。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-09
- **Last Updated**: 2026-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WSH — Windows by Linux Shell

在 Windows 上用 Linux 风格的命令行。WSH 把 `ls`、`cat`、`grep` 这类命令翻译为等价的 Windows 命令并执行，同时提供现代化的终端交互体验。

> **WSH** = **W**indows by **L**inux **S**hell

## 快速开始

```
# 源码运行
pip install -r requirements.txt
python main.py

# 或直接用打包好的单文件（无需安装 Python）
dist\wsh.exe
```

## 功能

| 功能 | 说明 |
|---|---|
| 内置 ls | Python 实现，彩色分栏，支持 `-l` / `-a` / `-h` |
| 内置 cat | 直接读文件输出，不走 `type` |
| 命令翻译 | `rm`→`del`、`grep`→`findstr`、`ifconfig`→`ipconfig` 等 |
| 参数翻译 | `cp -r`→`copy /e`、`rm -rf`→`del /s /q` |
| 管道 | `cat a.txt \| grep foo` |
| 重定向 | `>`、`>>`、`<`、`2>` |
| 别名 | `alias ll='ls -l'`，会话内持久化 |
| sudo | 以管理员身份运行命令（弹 UAC，新开窗口） |
| 内置字体 | 自动加载 Cascadia Code / JetBrains Mono，无需安装到系统 |
| 字体大小 | `--setting font size 18` 即时调整字号 |
| 主题 | 6 套配色（default / dracula / nord / gruvbox / monokai / light） |
| 右键菜单 | 文件夹 / 盘符右键 →「运行命令行」直接打开 |
| 会话持久化 | 关闭重开自动恢复上次目录和别名 |
| 交互体验 | 彩色提示符、Tab 补全（命令+路径）、`Ctrl+R` 搜历史、自动建议 |
| Git 分支 | 提示符自动显示当前分支 |
| QuickEdit | 鼠标拖选文本右键复制 / 右键粘贴 |
| 脚本模式 | `wsh.exe < script.txt` 逐行执行 |

## 命令

### Shell 命令

| 命令 | 说明 |
|---|---|
| `cd` | 切换目录（支持相对路径与 ~） |
| `pwd` | 打印当前工作目录 |
| `exit` | 退出 |
| `ls` | 列目录（`-l` / `-a` / `-h`） |
| `ll` | `ls -l` 的快捷方式 |
| `cat` | 输出文件内容 |
| `alias` / `unalias` | 查看 / 设置 / 删除别名 |
| `echo` | 输出一行文本 |
| `which` | 定位命令：内置 / 翻译 / 外部可执行 |
| `sudo` | 以管理员身份运行（`sudo notepad C:\Windows\hosts`） |

### 元命令

| 命令 | 说明 |
|---|---|
| `--help` / `-h` | 显示帮助 |
| `--version` | 显示版本号 |
| `--setting` | 查看所有设置状态 |
| `--setting menu on/off` | 安装 / 移除右键菜单 |
| `--setting font` | 查看当前字体 |
| `--setting font list` | 列出可用内置字体 |
| `--setting font <名称>` | 切换字体 |
| `--setting font size <N>` | 调整字号（14-32） |
| `--setting theme` | 列出所有主题 |
| `--setting theme <名称>` | 切换主题 |

## 提示符

```
WSH ~/winexe/wsh (main) >
WSH ~/winexe/wsh (main) [1] >    ← 上条命令失败
```

- `WSH` 紫色粗体，路径青色，Git 分支绿色，`>` 粉色
- 失败时显示红色退出码
- 启动窗口 100 列 × 30 行，缓冲区 9000 行可滚动

## 右键菜单集成

```
WSH > --setting menu on
  ✓ 右键菜单「运行命令行」已添加。
```

之后在文件夹空白处、文件夹本身、或盘符上右键即可看到。

> 移动 exe 后需先 `--setting menu off` 再 `on` 以更新路径。

## 目录结构

```
wsh/
├── main.py                  # 入口
├── requirements.txt
├── wsh.spec                 # PyInstaller 配置
├── dist/wsh.exe             # 打包产物（单文件）
├── shell/
│   ├── context.py          # 会话上下文
│   ├── tokenizer.py        # 词法分析
│   ├── parser.py           # 语法分析（管道 / 重定向）
│   ├── registry.py          # 命令注册表
│   ├── translator.py       # Linux→Windows 翻译
│   ├── executor.py         # 子进程执行
│   ├── repl.py             # 交互循环
│   ├── theme.py             # 配色主题（6 套）
│   ├── fontsetup.py         # 内置字体加载与切换
│   ├── pathcompleter.py    # 智能路径补全
│   ├── sessions.py          # 会话持久化
│   ├── shellmenu.py         # 右键菜单注册表操作
│   ├── paths.py             # 路径解析公共函数
│   ├── ui.py                # 共享 console 与输出函数
│   └── resource.py           # 打包资源路径
├── commands/
│   ├── builtins.py          # cd / pwd / exit / alias
│   ├── coreutils.py         # --help / echo / which
│   ├── listutils.py         # ls / ll / cat
│   ├── shellmenu.py         # --setting 命令
│   └── sudo.py              # sudo 提权
├── config/aliases.json      # 用户自定义映射
├── assets/
│   ├── icon.ico             # 程序图标
│   └── fonts/               # 内置字体（Cascadia Code / JetBrains Mono）
└── tests/
```

## 重新打包

```bash
pip install pyinstaller prompt_toolkit rich
python -m PyInstaller --noconfirm --clean wsh.spec
# 输出 dist\wsh.exe（约 11.5 MB）
```

## 扩展

**添加命令映射**：编辑 `config/aliases.json`

```json
{
  "names": { "ping": "ping -t" },
  "args": { "ls --color=auto": "" }
}
```

**添加内置命令**：在 `commands/` 下新建文件，写 `handler(ctx, argv) -> int` 并 `registry.register(...)`。

## 已知限制

- 通配符由 cmd 处理，行为与 Linux 略有差异
- 内置命令（如 `cd`）在管道中不生效
- 启动时自动执行 `chcp 65001` 切换 UTF-8 代码页，外部命令输出不再乱码
- 打包需在 Windows 上执行

## 测试

```bash
python tests\test_wsh.py     # 单元测试
python tests\smoke_test.py   # 端到端冒烟
```