Repository navigation

Releases

2.1.0 Latest

Latest

Qin-collab released this 04 Oct 07:48

v2.1.0

4a39a25

KShell 2.1.0 版本文档

版本：2.1.0（代号 Plugin）
发布日期：2026-10-04
开源协议：Apache License 2.0
支持平台：Windows 10/11 · macOS 10.15+ · Linux（主流发行版）
运行环境：Python 3.6+（核心零第三方依赖）

一、版本概览

KShell 2.1 的核心是插件系统：用「JSON 配置 + Python 实现」扩展终端，无需修改 KShell 本体。

配套地，官网新增开发者社区子路由与后台插件注册表管理。

项目	2.0.0	2.1.0
内置命令数量	68	69
扩展方式	修改源码	插件目录（免改源码）
插件系统	无	JSON 声明 + Python 实现 + 热重载
插件脚手架	无	`plugin new` 自动生成
插件配置	无	`plugin config` 持久化，支持类型推断
插件隔离	无	加载/执行异常均被隔离
开发者文档	无	PLUGIN_DEV.md + 社区页面
官网子路由	单页	`/community` 开发者社区
后台功能	5 个视图	6 个视图（新增插件社区）
打包体积	7.9 MB	约 12 MB（含插件标准库）

二、版本亮点

插件 = 2 个文件 — plugin.json（元数据+配置）+ plugin.py（实现），放进 plugins/ 即被自动发现。
热重载 — plugin reload 立即生效，改代码无需重启 KShell。
异常隔离 — 插件加载失败或执行出错只提示，不会拖垮 Shell。
脚手架 — plugin new myplugin 一键生成可运行的插件骨架。
配置系统 — 插件在 plugin.json 声明配置项，用户用 plugin config 覆盖并持久化。
开发者社区 — 官网 /community，含完整开发文档、示例源码与插件画廊。
后台插件管理 — 可视化增删改插件条目、控制发布状态与推荐置顶。

三、插件系统

3.1 插件结构

plugins/
└── myplugin/
    ├── plugin.json     元数据、命令声明、默认配置
    └── plugin.py       Python 实现

搜索目录（优先级从高到低，同名插件不被低优先级覆盖）：

顺序	目录	说明
1	`sys._MEIPASS/plugins`	打包内置（官方示例）
2	项目根 `plugins/`	源码运行
3	可执行文件同级 `plugins/`	用户插件推荐位置
4	`~/.kshell/plugins`	用户级
5	配置 `plugins.dirs`	自定义目录

3.2 plugin.json

{
  "name": "myplugin",
  "version": "1.0.0",
  "author": "你的名字",
  "description": "插件说明",
  "homepage": "https://github.com/you/myplugin",
  "kshell": ">=2.1.0",
  "enabled": true,
  "commands": {
    "myplugin": {
      "function": "cmd_main",
      "usage": "myplugin [参数] [-v]",
      "description": "命令说明",
      "aliases": ["mp"]
    }
  },
  "settings": {
    "greeting": "Hello"
  }
}

commands 支持三种写法：

字符串数组 — ["hello", "greet"]，函数名约定为 cmd_<命令名>
对象 — 可指定 function / usage / description / aliases
省略 — 自动扫描 plugin.py 中所有 cmd_* 函数（cmd_auto_one → 命令 auto-one）

manifest 校验（不通过则只报错，不影响 KShell）：

校验项	说明
JSON 语法	解析失败直接报错
`name` 必填且合法	只允许字母、数字、`_`、`-`
`name` 与目录名一致	不一致时报错
`commands` 格式	必须是数组或对象
函数存在性	声明的函数必须在 `plugin.py` 中可调用
版本要求	`kshell` 字段与当前版本比对
`settings` 类型	必须是 JSON 对象

3.3 plugin.py 与 ctx API

def cmd_hello(args, options, ctx):
    greeting = ctx.get('greeting', 'Hello')     # 读插件配置
    name = args[0] if args else 'World'
    return 0, f'{greeting}, {name}!'            # (退出码, 输出)

ctx 提供：

成员	说明
`ctx.name` / `ctx.version` / `ctx.dir`	插件元信息
`ctx.get(k, d)` / `ctx.set(k, v)` / `ctx.config()`	插件配置读写
`ctx.fs` / `ctx.platform` / `ctx.settings` / `ctx.theme`	KShell 能力
`ctx.colorize(text, key)`	主题着色
`ctx.log(msg)`	日志（加载阶段打印）
`ctx.register_command(...)`	运行期动态注册命令

返回值归一化：(code, str) / str / None / int 都能正确处理。

可选回调：on_load(ctx) / on_unload(ctx)。

3.4 加载机制

动态编译：读取源码后 compile() + exec()，不使用 importlib 的字节码缓存
- 原因：CPython 的 .pyc 过期判断依赖「源文件 mtime（秒级）+ 文件大小」，同秒内改动等长代码会命中旧字节码，导致热重载失效
- 附带好处：不会在用户的插件目录里生成 __pycache__
异常隔离：导入异常 → 记录 load_error；执行异常 → 返回 (1, 错误信息)
配置持久化：plugins.enabled / plugins.config / plugins.dirs 写入 kshell_config.json
目录可写性检测：plugin new 会实测目录可写，且排除打包临时目录（_MEIPASS 退出即删）

3.5 官方示例插件

插件	命令	演示内容
`hello`	`hello` `greet`	配置读取、选项解析、返回值、`on_load` 回调、别名
`pwgen`	`pwgen` `uuid` `passwd-strength`	多命令插件、命令名与函数名不同、`secrets` 加密安全随机
`sysinfo`	`sysinfo` `sys`	`--json` 结构化输出、配置开关、优雅降级

四、plugin 命令

plugin                      # 列出全部插件
plugin list                 # 同上
plugin info <名称>           # 详情：元数据、命令、配置、失败原因
plugin enable <名称>         # 启用（写入配置）
plugin disable <名称>        # 禁用（写入配置）
plugin reload [名称]         # 重新加载（省略名称则全部）
plugin config <名称>         # 查看插件配置
plugin config <名称> k=v     # 修改插件配置（自动推断类型）
plugin dirs                 # 显示插件搜索目录
plugin new <名称>            # 生成插件骨架
plugin help                 # 子命令帮助

配置值类型推断：true/false → 布尔，123 → 整数，1.5 → 浮点，null → None，其余为字符串。

示例：

$ plugin new myplugin
插件骨架已生成: D:\KShell\plugins\myplugin

$ plugin reload myplugin
插件 myplugin 已重新加载（1 条命令）

$ plugin config myplugin greeting=你好
已更新插件 myplugin 的配置: greeting

$ plugin list
KShell 插件（4 个）
  名称            版本      状态    命令数  说明
  hello          1.0.0     已加载     2    最小示例插件…
  myplugin       0.1.0     已加载     1    myplugin 插件
  pwgen          1.0.0     已加载     3    密码与 UUID 生成器…
  sysinfo        1.0.0     已加载     2    系统信息速查…

  已加载 4 · 禁用 0 · 失败 0 · 注册命令 8 条

五、开发者社区

5.1 官网子路由 `/community`

面向插件开发者的文档页，包含：

30 秒上手 —— 脚手架命令演示
插件结构 —— 目录约定与搜索优先级
plugin.json 字段 —— 完整字段表 + 三种 commands 写法
plugin.py 实现 —— 函数签名、选项解析注意点
ctx 上下文 API —— 全部成员与着色 key
返回值约定 —— 四种返回形式与异常隔离行为
官方示例插件 —— 三个插件的真实源码（选项卡切换）
插件画廊 —— 从 /api/plugins 动态加载，支持标签筛选
提交你的插件 —— 步骤与发布前自查清单
安全须知 —— 权限模型与注意事项

页面自带侧栏目录（滚动高亮）、代码复制按钮、移动端适配。

5.2 后台插件管理

后台新增「插件社区」视图：

功能	说明
注册表统计	条目总数、已发布、官方、推荐位、标签汇总
新增/编辑	表单包含名称、版本、作者、说明、仓库、命令、标签
发布控制	未发布的条目只在后台可见，不出现在前台
推荐置顶	标记推荐后在前台画廊中优先排序
官方标记	显示「官方」徽章
删除	二次确认
补回官方示例	幂等操作，仅补齐缺失的内置条目

字段校验（服务端白名单）：

字段	规则
`name`	必填，仅字母数字下划线连字符，最长 60
`version`	最长 20
`author`	最长 80
`description`	最长 400
`repo` / `homepage`	必须是 http(s) 链接
`commands`	最多 20 项，单项最长 40（支持逗号分隔输入）
`tags`	最多 8 项，单项最长 20（支持逗号分隔输入）
`published` / `featured` / `official`	布尔

5.3 公开接口

路径	说明
`GET /community`	开发者社区页面
`GET /api/plugins`	已发布的插件列表 + 标签汇总（带 120 秒缓存）

六、缺陷修复

2.1 开发过程中发现并修复的问题（多数由测试与截图验收暴露）：

#	问题	影响	修复
1	热重载读到旧代码	同秒内改动等长源码时，CPython 的 `.pyc` 过期判断（mtime 秒级 + 文件大小）会命中缓存字节码，`plugin reload` 不生效	改为直接读取源码 `compile()` + `exec()`，绕过字节码缓存
2	非 GBK 字符导致 Shell 崩溃	Windows 控制台默认 GBK，插件输出 `✓`、emoji 等字符会抛 `UnicodeEncodeError` 并中断整个 Shell	新增 `safe_print()`，所有输出走它，无法编码时降级替换
3	配置出现扁平重复键	`SettingsManager` 只支持扁平键，`plugins.config` 被当成字面键名写进配置，与嵌套默认值重复	为 `SettingsManager` 实现点号路径读写（含扁平键回退兼容）
4	打包后插件无法导入标准库	PyInstaller 静态分析看不到动态加载插件的 `import`，`pwgen` 在 exe 中报 `ModuleNotFoundError: secrets`	新增 `PLUGIN_STDLIB_HINTS` 清单，由 `kshell.spec` 导入并加入 `hiddenimports`
5	打包后脚手架写入临时目录	`plugin new` 把插件生成到 `_MEIPASS`（退出即删），用户拿不到文件	新增 `scaffold_dir()`：实测可写、排除临时目录，优先可执行文件同级
6	插件目录生成 `__pycache__`	早期 importlib 加载会在用户插件目录留下 `.pyc`	改为 compile/exec 后不再生成（已验证）

七、命令与配置

7.1 命令数量

类别	2.0	2.1
核心内置	36	36
扩展命令	32	32
插件管理	—	1（`plugin`）
合计	68	69

此外，插件会注册各自的命令（官方示例贡献 7 条）。

7.2 新增配置项

{
  "plugins": {
    "enabled": {},     // { "插件名": true/false }
    "config":  {},     // { "插件名": { "键": 值 } }
    "dirs":    []      // 额外插件搜索目录
  }
}

八、架构变化

8.1 新增模块

pluginmgr.py           插件系统核心
  · PluginManager      —— 发现、加载、注册、配置、脚手架
  · Plugin / PluginCommand —— 插件与命令描述
  · PluginContext      —— 传给插件函数的上下文
  · PLUGIN_STDLIB_HINTS —— 打包时需包含的插件常用标准库清单

commands_plugin.py     plugin 命令组实现

version.py             版本号单一来源（VERSION / check_requirement）

plugins/               官方示例插件
  hello/ pwgen/ sysinfo/

PLUGIN_DEV.md          插件开发指南

8.2 加载流程

terminal.__init__()
   │
   ├─ BuiltinCommands()            注册 36 核心命令
   │     └─ ExtraCommands()        注册 32 扩展命令
   │     └─ PluginCommands()       注册 plugin 命令
   │
   └─ PluginManager.load_all()
         │
         ├─ resolve_dirs()         解析搜索目录（含 _MEIPASS / 用户目录 / 配置）
         ├─ find_manifests()       扫描 plugin.json
         └─ load() 每个插件
               ├─ 解析并校验 plugin.json
               ├─ 版本要求比对
               ├─ 启用状态检查
               ├─ 读取源码 → compile() → exec()    ← 绕过字节码缓存
               ├─ 包装并注册命令（异常隔离 + 返回值归一化）
               └─ 调用 on_load(ctx)

8.3 命令派发顺序（未变）

command 强制系统命令 → 内置命令（含插件命令）→ 系统 PATH 命令

插件命令与内置命令同级，因此插件命令会覆盖同名内置命令——这是有意设计（方便插件扩展/覆盖行为），但插件开发者应避免与内置命令重名。

九、从 2.0 升级

9.1 兼容性

✅ 配置文件兼容 — 2.0 的 kshell_config.json 可直接使用，plugins 段会自动补齐默认值。
✅ 命令语法兼容 — 所有 2.0 命令行为不变。
✅ 脚本兼容 — .ksh 脚本无需修改。
✅ 旧版配置的扁平键兼容 — 若存在 "plugins.config" 这类扁平键，SettingsManager 读取时会回退匹配。

9.2 行为变更

变更	说明
新增 `plugin` 命令	若你之前自定义过 `plugin` 命令，会被覆盖
启动时扫描插件目录	首次启动稍慢（毫秒级）；插件加载失败会在启动时提示
新增 `plugins` 配置段	老配置会自动补默认值
打包体积增加	约 7.9 MB → 12 MB，因为纳入了插件常用标准库模块

9.3 升级步骤

Windows

:: 备份配置
copy kshell_config.json kshell_config.json.bak

:: 用新的 exe 替换（可选：在 exe 同级建 plugins 目录放插件）
kshell_windows_x64_v2.1.exe

验证

kshell            # 横幅应显示 KShell v2.1
plugin list       # 应列出 3 个官方示例插件
plugin help       # 应输出子命令帮助
hello KShell      # 应输出 Hello, KShell!

十、安装方式

Windows

kshell_windows_x64_v2.1.exe            :: 交互模式
kshell_windows_x64_v2.1.exe script.ksh :: 脚本模式

重新构建：

packaging\build_windows.bat

打包时会把 plugins/（官方示例）与 PLUGIN_DEV.md 一并内嵌。用户自己的插件放在 exe 同级 plugins/ 目录 即可。

Linux

# APT 仓库
echo "deb [trusted=yes] http://39.96.82.163/apt stable main" | sudo tee /etc/apt/sources.list.d/kshell.list
sudo apt update && sudo apt install -y kshell

# 或源码
git clone https://github.com/Qin-collab/KShell.git
cd KShell && python3 kshell.py

...

Assets 3

2.0.0

Qin-collab released this 02 Oct 08:42

v2.0.0

771af75

KShell 2.0.0 版本文档

版本：2.0.0
发布日期：2026-10-02
开源协议：Apache License 2.0
支持平台：Windows 10/11 · macOS 10.15+ · Linux（主流发行版）
运行环境：Python 3.6+（核心零第三方依赖）

一、版本概览

KShell 2.0.0 是继 1.0.0 之后的第一个功能版本，核心主题是打通与操作系统命令行的边界。

1.0 版本已经实现了完整的终端框架（解析、内置命令、主题、配置、脚本），但它与系统命令之间存在明显的割裂：系统命令的选项会被解析器丢弃，管道不能传递数据，Windows 的 dir、ver 等命令完全无法调用。

2.0.0 解决的就是这些问题，并确立了明确的命令优先级规则。

项目	1.0.0	2.0.0
内置命令数量	66	68
系统命令直通	部分（选项会丢失）	完整（argv 透传）
内置/系统优先级	隐含，不可配置	显式规则 + 可配置
Windows cmd 内部命令	不支持	支持 42 个
管道数据传递	不传递	上游输出作为下游 stdin
强制系统命令	无	`command` 内置命令
新增命令	—	`path`、`calc`

二、版本亮点

系统 PATH 命令直接使用 — 系统里装了什么就能用什么，git、docker、python、ipconfig 一律直通，选项完整保留。
内置命令优先 — 同名命令优先走 KShell 自己的实现，行为可预测；需要系统版本时用 command 绕过。
新增 path 命令 — 查看/搜索/管理 PATH，并可视化"哪些系统命令被内置命令接管"。
新增 calc 命令 — 基于 AST 安全求值的计算器，支持运算符优先级与括号。
新增 syscmd.py 模块 — 独立的系统命令解析层，启动扫描 PATH 并建立索引。
修复 7 项缺陷 — 其中"外部命令选项被丢弃"和"管道不传数据"是影响最大的两个。

三、新特性详解

3.1 系统 PATH 命令直通

系统 PATH 中的任何命令都可以直接输入执行，无需任何配置或包装。

git status                  # 调用系统 git
python --version            # 调用系统 python
ipconfig /all               # Windows 命令，选项完整透传
docker ps -a                # 任意已安装命令
ping -n 2 127.0.0.1         # -n 2 不会丢失

实现原理（syscmd.py）：

启动时扫描 PATH 的所有目录，建立 命令名 → 可执行文件路径 索引
Windows 下识别 PATHEXT 扩展名（.exe / .cmd / .bat / .com 等）
Windows 下额外注册 cmd.exe 内部命令（dir、ver、title、color 等 42 个，磁盘上没有对应文件）
命令未命中时，按 5 秒间隔惰性重新扫描，因此新安装的软件无需重启 KShell

注意：命令名在 Unix 下区分大小写，在 Windows 下不区分。PATH 中靠前的目录优先。

3.2 内置命令优先

当同名命令同时存在于 KShell 内置和系统 PATH 时，默认执行 KShell 的内置实现。

ls -l            # 走 KShell 内置 ls
grep foo f.txt   # 走 KShell 内置 grep
find . -name a   # 走 KShell 内置 find

为什么要这样做：内置实现行为确定、输出统一（含主题着色）、且不依赖系统是否安装了 GNU 工具链。在 Windows 上尤其重要——系统根本没有 ls、grep。

强制执行系统版本（bash 风格的 command 内置命令）：

command ls -l    # 强制系统 ls
command find .   # 强制系统 find
command dir      # 走 cmd.exe 的 dir

切换优先级规则：

config set builtin_priority false   # 改为系统命令优先（系统没有时回退内置）
config set builtin_priority true    # 恢复默认：内置优先

查看哪些命令被接管：

path -b

3.3 `path` 命令（新增）

管理并检视系统 PATH。

用法	说明
`path`	列出所有 PATH 目录（标注不存在的目录）+ 系统/内置命令总数
`path -s <关键字>`	搜索系统命令，标注 `[内置优先]` 与被接管的命令
`path -b`	列出所有被内置命令优先接管的系统命令
`path -a <目录>`	向 PATH 添加目录（仅当前会话）
`path -r <目录>`	从 PATH 移除目录（仅当前会话）
`path -F`	强制重新扫描系统命令

示例：

$ path
PATH 目录（共 12 个）:
   1. C:\WINDOWS\system32
   2. C:\WINDOWS
   ...
  12. C:\Users\me\AppData\Local\Microsoft\WindowsApps

系统命令总数: 4832
内置命令总数: 68
提示: path -s <关键字> 搜索系统命令 | path -b 查看被接管的命令

$ path -s git
  git
    C:\Program Files\Git\cmd\git.exe
  共 1 条

path -a / path -r 的修改仅对当前会话有效，不会写入系统环境变量。

3.4 `calc` 命令（新增）

内置计算器，使用 AST 安全求值，不使用 eval。

$ calc 1+2*3
7
$ calc (1+2)*3
9
$ calc 2**10
1024
$ calc 10/4
2.5
$ calc 10//3
3
$ calc 7%3
1

支持的运算符：+ - * / // % ** 与括号。

仅允许数字常量与算术运算，函数调用、属性访问、导入语句一律拒绝：

$ calc __import__("os").system("rm -rf /")
计算错误: 表达式包含不支持的语法

3.5 管道数据真正传递

上游命令的输出作为下游命令的标准输入，内置命令与系统命令可以自由混合。

ls | findstr .py                 # 内置 ls → 系统 findstr
cat app.log | grep ERROR | head  # 内置 cat → 内置 grep → 内置 head
python gen.py | sort | uniq      # 系统 python → 内置 sort → 内置 uniq

四、缺陷修复

#	问题	影响	修复方式
1	外部命令选项被解析器丢弃	`ping -n 2 host` 实际执行 `ping 2 host`；`git --version` 参数丢失	新增 `CommandParser.raw_split()`，把别名展开后的原始 token 列表完整透传给系统命令
2	管道不传递数据	`ls \| findstr .py` 的上游输出被直接丢弃，下游读不到数据	`run_system()` 新增 `stdin_data` 参数，上游输出作为下游 `input`
3	`ls <文件>` 无输出	对单个文件路径执行 `ls` 返回空，与 GNU 行为不符	`FileSystem.list_dir()` 检测文件目标并返回文件自身；`cmd_ls` 同步修正路径拼接
4	非 UTF-8 输出导致崩溃	Windows 下 GBK 编码输出触发 `UnicodeDecodeError`	`subprocess.run()` 增加 `errors='replace'`
5	`calc` 未注册且调用不存在的 API	命令落到系统 `calc.exe`，在受限环境下报 `WinError 5`	正式注册命令，并改用以 `ast` 为基础的安全求值器；修正为 `theme.colorize(text, 'error')`
6	`ExtraCommands` 缺少 `theme` 属性	任何使用主题着色的扩展命令都会 `AttributeError`	`__init__` 中补充 `self.theme = getattr(builtin, 'theme', None)`
7	命令不存在时返回码不准	统一返回 `1`，无法与一般错误区分	返回标准的 127（命令不存在）、126（权限不足）、130（被中断）

五、命令参考

5.1 内置命令（36 条）

分类	命令
目录操作	`cd` `pwd` `ls` `dir` `clear` `cls`
文件操作	`mkdir` `md` `rmdir` `rd` `rm` `del` `cp` `copy` `mv` `move` `cat` `type` `touch`
输出	`echo`
会话	`history` `exit` `quit`
帮助与配置	`help` `config` `theme`
环境变量	`env` `set` `unset` `export`
别名	`alias` `unalias`
系统信息	`date` `time` `whoami` `hostname`

dir cls md rd del copy move type 是 Windows 风格别名，分别映射到 ls clear mkdir rmdir rm cp mv cat。

5.2 扩展命令（32 条）

分类	命令
权限	`sudo`
文本处理	`head` `tail` `grep` `wc` `sort` `uniq` `nl` `tee`
查找与信息	`find` `tree` `stat` `du` `df` `which`
系统	`ps` `kill` `sleep` `uptime` `uname` `id`
工具	`base64` `md5sum` `sha256sum` `sha1sum` `seq` `yes` `true` `false` `man`
v2.0 新增	`path` `calc`

5.3 系统命令（数量取决于环境）

任何存在于 PATH 中的可执行文件都可直接调用，无需登记。Windows 下额外支持 cmd.exe 内部命令：

assoc  break  call  chdir  cls   color  copy   date   del    dir
echo   endlocal  erase  exit   for   ftype  goto   if     md     mkdir
mklink move   path   pause  popd  prompt pushd  rd     rem    ren
rename rmdir  set    setlocal shift start  time   title  type   ver
verify vol

5.4 退出码

退出码	含义
`0`	成功
`1`	一般错误
`126`	权限不足
`127`	命令不存在
`130`	被 Ctrl+C 中断
`-1`	KShell 内部信号（`exit` 命令，退出终端）

退出码由终端内部记录（Terminal.exit_code）。当前版本未实现 $? 变量展开，因此脚本中无法直接读取上一条命令的退出码。

六、配置项

配置文件位于当前工作目录下的 kshell_config.json（v2.0 起不再纳入版本控制）。

配置项	类型	默认值	说明
`banner_enabled`	bool	`true`	是否显示启动横幅
`history_size`	int	`1000`	命令历史保留条数
`prompt_style`	string	`default`	提示符样式：`default` / `simple` / `poweruser`
`use_colors`	bool	`true`	是否启用 ANSI 颜色（管道/重定向时自动关闭）
`welcome_message`	string	`Welcome to KShell!`	自定义欢迎语（保持默认值则不额外显示）
`aliases`	object	`{}`	持久化别名表，重启后仍生效
`environment`	object	`{}`	自定义环境变量
`theme`	string	`default`	颜色主题
`builtin_priority`	bool	`true`	v2.0 新增：内置命令是否优先于系统同名命令

内置主题（6 套）

default · dark · light · ocean · monokai · solarized

theme list          # 列出所有主题
theme preview       # 预览所有主题配色
theme ocean         # 切换到 ocean

配置操作

config              # 列出所有配置
config get theme    # 读取单项
config set theme ocean           # 修改
config set builtin_priority false  # 切换优先级规则
config reset        # 恢复默认

七、架构变化

7.1 模块结构

kshell.py                  程序入口（交互模式 / 脚本模式）
  │
  └── terminal.py          调度中枢：主循环、优先级派发、管道、重定向
        │
        ├── syscmd.py      【v2.0 新增】系统 PATH 命令解析
        │                    · SystemCommandResolver  —— PATH 扫描与索引
        │                    · SystemCommand          —— 命令描述（可执行/cmd内部）
        │                    · WINDOWS_CMD_BUILTINS    —— cmd.exe 内部命令集合
        │
        ├── process.py     进程管理：run_system() 完整 argv 透传
        ├── parser.py      命令解析：parse() 选项提取 + raw_split() 原始切分
        ├── filesystem.py  文件系统：pathlib + shutil
        ├── builtin.py     36 条内置命令
        ├── commands_extra.py  32 条扩展命令（含 path、calc）
        ├── settings.py    配置持久化（JSON）
        ├── theme.py       6 套主题与 ANSI 着色
        ├── banner.py      启动横幅
        └── kplatform.py   平台抽象（避免与标准库 platform 冲突）

7.2 命令派发流程

用户输入
   │
   ▼
parser.expand_alias()          别名展开
   │
   ├──► parser.raw_split()     → 原始 token 列表（供系统命令透传）
   └──► parser.parse()         → (命令, 位置参数, 选项字典)（供内置命令使用）
   │
   ▼
terminal._execute_command()
   │
   ├─ command == 'command' ？ → 强制走系统命令
   │
   ├─ builtin_priority == true（默认）
   │     ├─ 是内置命令 → builtin.execute()
   │     └─ 否         → process_manager.run_system()
   │
   └─ builtin_priority == false
         ├─ PATH 中存在该命令 → run_system()
         ├─ 否则是内置命令    → builtin.execute()
         └─ 都不是            → 返回 127
   │
   ▼
输出处理
   ├─ 有重定向 → strip_ansi() 去色后写入文件
   └─ 无重定向 → 打印（echo -n 不补换行）

7.3 关键设计决策

为什么解析两遍？ 内置命令需要结构化的 选项字典（如 ls -la → {l: True, a: True}），而系统命令需要原封不动的 argv（如 ping -n 2 中 -n 必须带值）。1.0 用同一套解析结果服务两者，导致系统命令选项丢失。2.0 改为 parse() + raw_split() 双通道，各取所需。

为什么内置优先而非系统优先？ Windows 上没有 ls/grep/sort，若系统优先，同一份脚本在 Linux 与 Windows 上行为不一致。内置优先保证了跨平台一致性，同时用 command 提供逃生舱。

八、从 1.0 升级

8.1 兼容性

✅ 配置文件向后兼容 — 1.0 的 kshell_config.json 可直接使用，缺失的键（如 builtin_priority）会自动补默认值。

✅ 命令语法兼容 — 所有 1.0 命令的参数形式不变。

✅ 脚本文件兼容 — .ksh 脚本无需修改。

8.2 行为变更（需注意）

变更	1.0 行为	2.0 行为	影响
系统命令选项	被丢弃	完整传递	之前"看似生效"的命令现在会真正带选项执行
管道	不传数据	传递数据	之前输出全部内容，现在会被下游过滤
命令不存在	返回 1	返回 127	依赖退出码判断的脚本需调整
`ls <文件>`	无输出	输出该文件	属于修复
`calc`	落到系统 `calc.exe`	KShell 内置计算器	如需系统计算器用 `command calc`
`kshell_config.json`	纳入版本控制	已 gitignore	克隆后首次运行自动生成

8.3 升级步骤

Windows（可执行文件）

:...

Assets 3

1.0.0

Qin-collab released this 25 Sep 08:03

v1.0.0

f5e92c9

KShell 1.0.0 介绍

一句话定位

KShell 是一个纯 Python 编写的跨平台终端，零 GUI 依赖、零外部依赖，一个文件即可开箱即用。

它支持 Windows / macOS / Linux，提供 60+ 条常用命令、主题切换、别名系统、脚本执行和管道重定向，适合作为轻量级命令行环境或学习 Shell 原理的参考实现。

核心特性

纯 Python 实现：不依赖 PyQt/Tkinter 等 GUI 库，核心逻辑不使用 os 模块
跨平台：Windows（kshell.exe）、Linux（.deb / apt install）、macOS（源码运行）
60+ 命令：cd/ls/cp/mv/grep/find/sudo/ps/kill/base64/md5sum/sha256sum/head/tail/wc/sort/uniq/tree/seq/...
主题系统：default / dark / light / ocean / monokai / solarized，自动检测是否支持颜色
别名系统：支持自定义 alias，重启后仍然生效
脚本执行：运行 .ksh 脚本文件，支持管道与重定向
配置持久化：JSON 配置文件，保存主题、别名、历史等
启动横幅：可开关的 ASCII 欢迎界面

Assets 5

2.1.0

KShell 2.1.0 版本文档

目录

一、版本概览

二、版本亮点

三、插件系统

3.1 插件结构

3.2 plugin.json

3.3 plugin.py 与 ctx API

3.4 加载机制

3.5 官方示例插件

四、plugin 命令

五、开发者社区

5.1 官网子路由 /community

5.2 后台插件管理

5.3 公开接口

六、缺陷修复

七、命令与配置

7.1 命令数量

7.2 新增配置项

八、架构变化

8.1 新增模块

8.2 加载流程

8.3 命令派发顺序（未变）

九、从 2.0 升级

9.1 兼容性

9.2 行为变更

9.3 升级步骤

十、安装方式

Windows

Linux

Uh oh!

2.0.0

KShell 2.0.0 版本文档

目录

一、版本概览

二、版本亮点

三、新特性详解

3.1 系统 PATH 命令直通

3.2 内置命令优先

3.3 path 命令（新增）

3.4 calc 命令（新增）

3.5 管道数据真正传递

四、缺陷修复

五、命令参考

5.1 内置命令（36 条）

5.2 扩展命令（32 条）

5.3 系统命令（数量取决于环境）

5.4 退出码

六、配置项

内置主题（6 套）

配置操作

七、架构变化

7.1 模块结构

7.2 命令派发流程

7.3 关键设计决策

八、从 1.0 升级

8.1 兼容性

8.2 行为变更（需注意）

8.3 升级步骤

Uh oh!

1.0.0

KShell 1.0.0 介绍

一句话定位

核心特性

Uh oh!

5.1 官网子路由 `/community`

3.3 `path` 命令（新增）

3.4 `calc` 命令（新增）