MineShell

A Unix-style shell experience inside Minecraft (Fabric)

让你用 Shell 思维操作 Minecraft 世界与本地文件。

---

项目简介

MineShell 是一个面向 Minecraft 的 Shell 内核与终端体验，不是简单的“命令增强”。 它提供了类似 Linux 的命令、管道、补全与终端交互模式，支持把世界对象与文件数据作为流进行处理。

核心目标：

• 用小命令 + 管道组合完成复杂任务
• 在 Minecraft 中保留熟悉的终端工作流
• 保持核心执行层与 UI 层解耦，便于扩展和测试

---

当前特性

• 管道执行：cmd1 | cmd2 | cmd3
• 虚拟文件系统（VFS）隔离：路径限制在游戏目录范围内
• 玩家会话状态：工作目录 (PWD) 按玩家保持
• 专用终端 GUI：
  • 快捷键打开（默认 `）
  • 历史命令（Up/Down）
  • 候选补全面板（Tab / Shift+Tab）
  • 输出选区复制（字符级拖拽）
• 语法解析基于 ANTLR，支持可扩展 DSL
• 命令输出支持分流渲染（stdout / stderr）

---

环境要求

• Minecraft 1.21.1
• Fabric Loader >= 0.18.4
• Fabric API 0.116.8+1.21.1
• Java 21

版本以 gradle.properties 与 fabric.mod.json 为准。

---

安装与运行

作为玩家使用

1. 构建或下载 MineShell 的 .jar
2. 放入 Minecraft 的 mods 目录
3. 使用 Fabric 启动游戏

作为开发者运行

# 构建
./gradlew build

# 启动开发客户端
./gradlew runClient

Windows 使用：

.\gradlew.bat build
.\gradlew.bat runClient

---

快速开始

方式 1：GUI 终端（推荐）

• 按 ` 打开 MineShell 终端
• 输入命令后 Enter 执行

方式 2：聊天命令

/ms <command>

示例：

/ms pwd
/ms ls
/ms cd config
/ms cat options.txt

---

内置命令

命令	说明	示例
echo	输出文本	echo hello
pwd	显示当前目录	pwd
cd	切换目录	cd config
ls	列出目录内容（支持 -a, -l, -la）	ls -la
cat	读取文件	cat options.txt
grep	过滤文本/对象流（支持 -i, -v, -n）	`ls
find	查找世界对象（方块/实体/玩家）	find -b stone
tree	树状展示目录（支持 -a, -L）	tree -L 2 config/
man	查看命令帮助	man ls

---

管道示例

ls | grep -i mod
find -b stone | grep -i ore
tree config/ | grep fabric

---

路径规则

• /：游戏目录根
• ~：等价于 /
• ..：上级目录（不会越过根目录）
• 相对路径：基于当前 PWD

示例：

pwd
cd config/fabric/
pwd
cd ..
pwd

---

终端交互键位

• `：打开终端
• Enter：执行命令
• Up/Down：历史命令
• Tab：打开/切换补全候选
• Shift+Tab：反向切换候选
• Esc：关闭补全面板或关闭终端
• Ctrl+L：清空终端输出
• Ctrl+C：复制当前选区
• Ctrl+Shift+A：全选输出
• Ctrl+Shift+C：复制全部输出

---

架构概览

UI Layer (GUI / Chat)
  -> Runtime (MineShellRuntime)
    -> Pipeline Executor
      -> Commands (MineCommand)
        -> Parser (ANTLR)
        -> Adapters (World / Player / VFS)
        -> IO Channels (stdin/stdout/stderr)

设计原则：

• Runtime 作为唯一执行入口
• 命令只通过 CommandIO 与 ExecutionContext 交互
• Parser 不包含执行逻辑
• VFS 控制所有文件访问边界

---

开发指南

添加新命令

1. 实现 MineCommand
2. 提供对应 CommandFactory
3. 在 Mineshell.initializeRuntime() 注册命令
4. 为命令补充 getHelp() 与 getDescription()

示例注册：

registry.register("mycmd", new MyCommand.MyCommandFactory());

---

Roadmap

• 重定向支持：>, >>, <
• 变量扩展：$VAR, ${VAR}
• 更多文本处理命令（如 sort, uniq, head, tail）
• 脚本执行（.ms）
• 更完整的终端体验（分页、搜索、主题）

---

贡献

欢迎提 Issue / PR。

建议：

• 保持分层架构清晰
• 新增命令附带帮助文本
• 提交前至少通过 ./gradlew build

---

许可证

本项目使用 GNU GPL v3.0，详见 LICENSE.txt。

---

致谢

• Fabric
• ANTLR
• Unix/Linux Shell 生态