用于通过 USB 串口连接 M5Stack CoreS3，并在主机终端中管理设备文件系统的命令行工具。
当前版本聚焦于 /flash 用户区文件管理：
- 列出串口与验证连接
- 浏览远端目录与树
- 创建目录
- 上传/下载文件
- 删除文件和空目录
- 将本地目录单向同步到设备
- 打开交互式 REPL
安全默认值：首版拒绝写入
/system，并拒绝删除/、/flash、/system等危险路径。
cores3ctl/
pyproject.toml
README.md
cores3ctl/
__main__.py
cli.py
config.py
errors.py
output.py
paths.py
remote_fs.py
repl_protocol.py
serial_transport.py
sync.py
tests/
在项目根目录下执行：
python -m pip install -e .\cores3ctl如果没有安装 pyserial，上面的命令会一并安装。
在当前项目环境中，也可以直接安装到根目录的 uv 虚拟环境：
uv pip install --python ./.venv/bin/python -e ./cores3ctl安装完成后，可直接使用：
./.venv/bin/cores3ctl ports
./.venv/bin/cores3ctl pingcores3ctl 现在会自动优先选择当前系统里最像 CoreS3 的串口设备。也可以用环境变量固定端口：
export CORES3CTL_PORT=/dev/cu.usbmodem11201
./.venv/bin/cores3ctl ping注意：同一时间只应有一个
cores3ctl命令占用设备串口；并发访问同一串口会导致pyserial报错。
在本项目根目录下，推荐直接使用 uv 或根虚拟环境中的命令入口：
uv run cores3ctl ports
uv run cores3ctl ping
uv run cores3ctl info
uv run cores3ctl sync . /flash --git --progress或者：
./.venv/bin/cores3ctl ports
./.venv/bin/cores3ctl ping
./.venv/bin/cores3ctl info
./.venv/bin/cores3ctl sync . /flash --git --progress当前 macOS 实机环境下，设备串口示例为：
/dev/cu.usbmodem11201默认串口参数：
- 端口：
COM20 - 波特率：
115200
cores3ctl portscores3ctl --port COM20 ping
cores3ctl --port COM20 infocores3ctl ls /flash
cores3ctl ls apps
cores3ctl tree /flash/res
cores3ctl stat /flash/main.py相对远端路径会自动按 /flash 解析，因此 apps/demo.py 等价于 /flash/apps/demo.py。
cores3ctl mkdir /flash/apps/demo
cores3ctl mkdir -p /flash/apps/demo/subdircores3ctl put .\local.py apps\local.py
cores3ctl put .\logo.png /flash/res/img/logo.png上传采用“先写临时文件，再重命名”的方式，避免中途失败破坏目标文件。
如需在交互终端中显示传输进度：
cores3ctl --progress put .\local.py apps\local.py进度信息写到
stderr，最终结果 JSON 仍写到stdout，便于脚本继续解析。
如需禁止覆盖已存在文件：
cores3ctl put .\local.py apps\local.py --no-forcecores3ctl get /flash/main.py .\downloads\main.py
cores3ctl get /flash/res/img/logo.png .\downloads\如需显示下载进度：
cores3ctl --progress get /flash/main.py .\downloads\main.py当前第一版下载进度会在完成时输出最终传输状态；后续可继续增强为真正的块级实时进度。
cores3ctl rm /flash/apps/demo/temp.txt
cores3ctl rmdir /flash/apps/demo/empty_dir首版 rmdir 仅支持删除空目录，不支持递归删除。
cores3ctl sync .\assets /flash/apps/assets --dry-run
cores3ctl sync .\assets /flash/apps/assetssync 当前默认仍是单向上传同步：
- 本地有、远端无：上传
- 文件大小不同：覆盖上传
- 文件大小相同：跳过
- 不会删除远端多余文件
默认排除：.git、.venv、__pycache__、.pytest_cache、.ruff_cache 等目录。
可额外传入：
cores3ctl sync .\assets /flash/apps/assets --exclude node_modules --exclude dist如需显示同步中每个上传操作的进度：
cores3ctl --progress sync .\assets /flash/apps/assetssync 也支持基于 Git commit 的代码部署，用于把当前仓库 HEAD 或指定 revision 的文件快照同步到设备，并在设备端记录当前已部署版本。
首次初始化同步必须显式给出 scope，例如只同步 main.py 与 lib：
cores3ctl sync . /flash/app --git --scope ./main.py --scope ./lib --dry-run
cores3ctl sync . /flash/app --git --scope ./main.py --scope ./lib设备端会在目标目录下创建：
/flash/app/.cores3ctl-sync.json
其中记录：
- 当前已部署的 git commit hash
- 当前受管的 scope 范围
- 对应的 remote_dir
查看设备端当前 Git 同步状态：
cores3ctl sync . /flash/app --git --status从指定 revision 同步：
cores3ctl sync . /flash/app --git --rev 0123456 --scope ./main.py --scope ./lib后续增量同步会根据设备端记录的 git_rev + scope 与本次目标 revision 做 Git 文件级 diff：
A：新增文件，上传M：修改文件，上传D：删除文件，设备端删除R*：重命名文件，优先在设备端 rename，必要时 fallback 为上传新文件再删除旧文件
真正开始传输前，CLI 会先列出本次计划同步的文件变更。除此之外，Git 模式还会额外核对设备端目标文件的存在性、类型和文件大小；即使 Git diff 没有显示该文件变化，只要设备端文件缺失或大小与目标快照不一致，也会自动补传。
如需强制对当前 scope 全量重传：
cores3ctl sync . /flash/app --git --force-full如需更新设备端记录的 scope：
cores3ctl sync . /flash/app --git --scope ./main.py --scope ./lib --update-scope注意：Git 模式同步的是已提交内容（默认
HEAD，或--rev指定 revision），不会自动携带未提交工作区改动。
cores3ctl exec "print('hello from raw repl')"
cores3ctl replrepl 模式下，输入 Ctrl+] 后回车可退出主机侧会话。
- 使用
pyserial打开 CoreS3 的 USB CDC 串口。 - 每次执行前发送
Ctrl+C，尽量中断当前正在运行的脚本。 - 通过 raw REPL 执行结构化脚本，并用
@@OK@@/@@ERR@@标记结果。 - 远端文件上传与下载都采用 base64 分块传输，兼容文本与二进制文件。
- 路径保护逻辑集中在
paths.py，统一约束危险路径与/system写入。
运行单元测试：
python -m pytest .\cores3ctl\tests如果本机没有 pytest：
python -m pip install pytest当前还未实现，但设计上预留了空间：
set-main：把某个apps/*.py复制为/flash/main.pyreset- 更精确的文件差异比较（哈希）
- 更安全的递归删除
- 下载路径的真正块级实时进度（当前第一版主要完善了上传与同步上传进度）