csos-fsshell

一个在终端中运行的虚拟磁盘工具：对磁盘镜像文件进行分区、在分区上创建 FAT / ext4 文件系统，并浏览已有文件系统中的目录和文件。

基于 Ink（React 终端 UI）构建，纯 Node.js 实现，无原生依赖。

功能

• 新建虚拟磁盘：指定的文件不存在时，输入容量（支持 K / M / G / T 后缀）即可创建空白镜像。
• 分区表：初始化 MBR / GPT 分区表，新建 / 删除分区（MBR 最多 4 个主分区，GPT 最多 128 个），分区按 1 MB 对齐。
• 创建文件系统：自动选择或手动指定 FAT12 / FAT16 / FAT32 / ext4，并可设置卷标；也可选择不格式化。
• 格式化已有分区：覆盖式格式化（会弹出确认）。
• 清空数据：一键清除所有已格式化卷中的文件/目录，回到刚格式化完的初始状态；分区结构、文件系统类型与卷标保持不变（会弹出确认）。
• 识别已有磁盘：自动识别 MBR / GPT 分区表、整盘 FAT 卷（无分区表）以及每个分区的文件系统。
• 浏览与编辑文件系统（FAT 与 ext4 功能一致）：
  • 目录树导航（进入 / 返回上级），支持 长文件名（LFN）与中文文件名；
  • 显示大小、修改时间、属性（R/H/S/A）；
  • 回车预览文本文件，二进制文件以十六进制视图显示；
  • n 新建文件（可直接输入多行文本内容）、m 新建文件夹、d 删除文件或目录（目录递归删除）；
  • e 改写文本文件内容、r 重命名、c 剪切 + p 粘贴（同卷内移动）；
  • x 键把选中的文件或目录（递归）提取到当前工作目录。
• 命令行拷贝（宿主机 → 镜像）：无需进 TUI，一条命令把外部文件/目录拷贝到指定位置， 支持 --mkdirs 自动创建缺失目录、--overwrite 覆盖同名文件、-p 选择分区。

安装与运行

需要 Node.js 18+（推荐 22）。

# 从 npm 全局安装
npm install -g csos-fsshell
csfs D:\disks\test.img

# 或从源码构建
npm install
npm run build

# 启动，并直接打开/新建指定的镜像文件
node dist/cli.js D:\disks\test.img

# 或者全局链接后使用
npm link
csfs D:\disks\test.img

命令行拷贝

# 把宿主机文件拷贝到镜像指定位置（目标为完整文件路径）
csfs D:\disks\test.img cp ./a.txt /docs/a.txt --mkdirs
# 目标是已存在目录或以 / 结尾时，自动拼接源文件名
csfs D:\disks\test.img cp ./a.txt /docs/ --mkdirs --overwrite
# 目录递归拷贝：目标即目录本身（不存在则创建，已存在则合并）
csfs D:\disks\test.img cp ./dist /app --partition 1 --mkdirs --overwrite
# 长参数形式（--src/--dest 与位置参数二选一，--dst/--to 是 --dest 别名）
csfs D:\disks\test.img cp --src ./a.txt --dest /docs/a.txt --mkdirs --overwrite

• -p, --partition <n>：目标分区号（磁盘总览 # 列，1 起；整盘卷用 1；仅一个可写卷时可省略）。
• --mkdirs：自动创建目标路径上缺失的中间目录（不加则缺失报错；目录拷贝的末级本身总是允许创建）。
• --overwrite：目标已存在同名文件时覆盖（不加则报错；目录合并时对内部文件同样生效）。

3.0 起主命令为 csfs，旧命令 csos-fsshell 保留为同义别名，老脚本无需改动。

不传参数时进入开始界面，手动输入路径。

操作说明

| 界面 | 按键 | 功能 | | --- | --- | --- | | 全局 | Esc | 返回上一层（开始界面中为退出） | | 磁盘总览 | q | 退出程序 | | 文件浏览 | q | 返回磁盘总览 | | 磁盘总览 | ↑ ↓ | 选择分区或空闲区域 | | 磁盘总览 | Enter / b | 浏览分区（空闲区域则新建分区） | | 磁盘总览 | n | 新建分区 | | 磁盘总览 | f | 格式化所选分区 | | 磁盘总览 | d | 删除所选分区（只删除分区表记录，不擦除数据） | | 磁盘总览 | i | 初始化分区表 | | 磁盘总览 | W | 清空所有已格式化卷中的文件/目录（分区结构、文件系统类型与卷标不变） | | 表单 | Tab / ↑ ↓ | 切换字段 | | 表单 | ← → | 选择文件系统类型 | | 表单 | Enter / Esc | 确认 / 取消 | | 文件浏览 | Enter / → | 进入目录 / 预览文件 | | 文件浏览 | ← / Backspace | 返回上级目录 | | 文件浏览 | n | 新建文件（名称确认后进入文本编辑，Ctrl+S 保存） | | 文件浏览 | m | 新建文件夹 | | 文件浏览 | e | 改写文本文件内容（二进制或超过 256 KB 的文件不支持） | | 文件浏览 | r | 重命名文件或目录 | | 文件浏览 | c / p | 剪切 / 粘贴（把条目移动到当前目录，同卷内） | | 文件浏览 | d | 删除选中的文件或目录（目录递归删除，会弹出确认） | | 文件浏览 | x | 提取到当前目录 | | 文本编辑 | Ctrl+S | 保存文件 | | 文本编辑 | Enter | 换行（Tab 缩进） | | 文本编辑 | Esc | 取消，不保存 | | 预览 | ↑↓ PgUp PgDn g G | 滚动 |

危险操作（格式化、删除分区、初始化分区表、清空数据、删除文件/目录）都会弹出确认框，按 y 确认、n 取消。

技术细节

src/
  cli.tsx                 命令行入口（TUI 启动、cp 拷贝模式参数解析）
  core/                   与界面无关的磁盘 / 文件系统逻辑
    image.ts              镜像文件读写（扇区级）
    mbr.ts                MBR 分区表读写、空闲区域计算
    gpt.ts                GPT 分区表读写（保护性 MBR、主/备份头、128 项、CRC32/GUID）
    disk.ts               磁盘级操作：检查、新建/格式化/删除分区（MBR/GPT 双分支）
    extract.ts            文件 / 目录提取（镜像 → 宿主机）
    import.ts             文件 / 目录导入（宿主机 → 镜像，自动建目录/覆盖选项）
    entry.ts              与文件系统无关的目录条目 / 读写接口（FsEntry/FsReader/FsWriter）
    fs.ts                 文件系统类型联合（FAT / ext4）与分配单元辅助函数
    fat/geometry.ts       FAT 参数计算（簇大小、FAT 表长度、簇数校验）
    fat/mkfs.ts           FAT 格式化（引导扇区、FSInfo、FAT 表）
    fat/reader.ts         FAT 解析（引导扇区、簇链、目录项、长文件名）
    fat/writer.ts         FAT 写入（创建/删除/改写/重命名/移动、簇分配、长/短文件名）
    ext4/geometry.ts      ext4 几何规划（块组、GDT 大小、inode 密度、备份组规则）
    ext4/core.ts          ext4 核心（超级块/描述符/位图/inode/extent/目录项编解码与分配）
    ext4/mkfs.ts          ext4 格式化（超级块备份、GDT、位图、根目录、lost+found）
    ext4/reader.ts        ext4 解析（超级块探测、目录与文件读取）
    ext4/writer.ts        ext4 写入（创建/删除/改写/重命名/移动、块与 inode 分配）
  ui/                     Ink 界面
    App.tsx               路由、会话与对话框状态
    screens/              开始 / 新建镜像 / 磁盘总览 / 分区表单 / 文件浏览
    components.tsx        面板、表格、分区占用条、快捷键栏

• MBR 分区起始扇区按 2048 扇区（1 MB）对齐；GPT 可用区为 LBA 34 ~ 末尾保留 33 扇区之前，分区同样按 1 MB 对齐，大小按 1 MB 向下取整。
• FAT 类型按照 Microsoft 规范的簇数阈值判定（FAT12 < 4085 簇，FAT16 < 65525 簇，其余为 FAT32）。
• 创建的 FAT 卷与 pyfatfs 双向互通测试通过（由 Python 写入文件后本工具可读取）。
• 创建的 ext4 卷按内核文档与 e2fsprogs 布局实现：4 KiB 块、无日志、无校验、线性（非 htree）目录、sparse_super 备份；ext4 文件名大小写敏感、无 8.3 短名。
• 读取时可兼容 flex_bg、64 位描述符与 htree 目录；写入时遇到 metadata_csum / gdt_csum / inline_data / meta_bg / htree 目录会拒绝并提示。

限制

• 分区表支持 MBR（最多 4 个主分区）/ GPT（最多 128 个分区，含保护性 MBR 与主/备份头），暂不支持扩展分区。
• GPT 分区类型：FAT 系列使用 Microsoft 基本数据分区 GUID，ext4 / 未格式化使用 Linux 文件系统 GUID。
• 文件系统支持 FAT12 / FAT16 / FAT32 / ext4；TUI 支持创建 / 删除 / 改写内容 / 重命名 / 同卷内移动（含长文件名、中文），TUI 内暂不支持复制与跨分区移动；命令行 cp 支持宿主机文件/目录拷贝进镜像（含自动建目录、覆盖选项）；权限位不保留（统一常规文件/目录权限）。
• 镜像必须是原始（raw）格式，例如 .img；VHD / VMDK 等容器格式不受支持。
• 扇区大小固定为 512 字节。

开发

npm run build   # 编译 TypeScript 到 dist/
npm test        # 编译并运行单元测试（dist/test）
npm run dev     # 编译并启动

发版流程（本地手动，免浏览器 token 登录）

npm version 2.4.0 --no-git-tag-version  # 示例：同步 package.json 与 lock 的版本号
npm test                                # 构建并跑全量测试
git add package.json package-lock.json && git commit -m "..."
git tag v2.4.0 && git push origin master --tags
npm publish                             # 已用用户级 ~/.npmrc 的 automation token 免登录发布

说明：token 只存于用户级 ~/.npmrc（//registry.npmjs.org/:_authToken），不进仓库； 本仓库 .gitignore 已忽略项目级 .npmrc，防止 token 误提交。换机器时重设一次 npm config set //registry.npmjs.org/:_authToken <token> --location=user 即可。

测试覆盖：大小解析、FAT 类型选择、分区表增删与重叠检测、FAT16/FAT32/FAT12 的格式化与回读（含长文件名、子目录、文件内容）、文件/目录的创建与（递归）删除、内容改写、重命名、同卷内移动、清空数据保留结构、宿主机→镜像导入（自动建目录/覆盖语义，FAT/ext4），以及超级软盘（无分区表的整盘 FAT 卷）识别；ext4 的几何规划、格式化与探测、超级块备份一致性、文件/目录的创建与（递归）删除、内容改写、重命名、同卷内移动、大小写敏感文件名、清空数据保留类型，以及整盘 ext4 卷识别。