Merge pull request #3 from LanternCX/dev

v1.0.1

Author: LanternCX

.progress/PROGRESS.md

@@ -39,3 +39,4 @@ abc123d (or TBD)
 | Page ID | Date | Title | Path | Keywords |
 | --- | --- | --- | --- | --- |
 | 2026-03-03-1 | 2026-03-03 | Stabilized full deploy flow and improved onboarding UX | `.progress/entries/2026/2026-03-03-1.md` | deploy, mpremote, config-wizard, docs |
+| 2026-03-04-1 | 2026-03-04 | Added configurable device upload directory with scoped full wipe | `.progress/entries/2026/2026-03-04-1.md` | sync, device-upload-dir, full-mode, planner, mpremote |

.progress/entries/2026/2026-03-04-1.md

@@ -0,0 +1,27 @@
+# 2026-03-04-1
+
+## Date
+2026-03-04
+
+## Title
+Added configurable device upload directory with scoped full wipe
+
+## Background / Issue
+Users needed to deploy files into a specific directory on the target MicroPython device instead of always syncing to the device root. The existing full-sync wipe behavior also cleared the whole filesystem root, which was too broad once per-project upload directories are introduced.
+
+## Actions / Outcome
+- Approach 1: Added `device_upload_dir` to config defaults, parser, saver, and interactive wizard -> users can persist upload target directory via `init/config` without manual TOML edits.
+- Approach 2: Extended planner to accept `remote_base_dir` and prefix upload/delete remote paths while setting full-mode wipe target to that directory -> deployment operations are now scoped to configured destination.
+- Approach 3: Extended backend and executor to pass wipe target directory through to `mpremote` cleanup script, including path normalization and `/flash` compatibility handling -> full-mode cleanup no longer requires wiping device root when a target directory is configured.
+- Approach 4: Updated README and expanded regression tests across config/cli/planner/executor/backend/docs checks -> behavior is documented and protected by automated coverage.
+- Final approach: Combined config + planning + execution + docs + tests in one change set -> enabled directory-scoped uploads and safer full-sync semantics.
+
+## Lessons / Refinements
+- Scope-sensitive deployment behavior should be modeled in plan objects first, then propagated into execution to keep logic auditable and testable.
+- For embedded targets, destructive operations must default to least-surprise scope (target directory) when user intent is explicit.
+
+## Related Commit Message
+feat(sync): support configurable device upload directory
+
+## Related Commit Hash
+TBD

README.md

@@ -15,6 +15,8 @@
 
 如果你是第一次使用本项目，可以遵循以下步骤。
 
+阅读完本章之后，建议继续阅读 [在其他项目中安装为命令行工具](#install)
+
 ### 0) 环境要求
 
 - Python 版本：`>= 3.10`（推荐 `3.11`）
@@ -71,6 +73,8 @@ mpy-cli init
 
 `init` 会进入交互式配置向导（可扫描设备端口并选择），无需手动编辑配置文件。
 
+在 `plan/deploy` 交互模式下，如果未提供 `--port`，会自动扫描可用端口并提示选择。
+
 初始化后会生成：
 
 - `.mpy-cli.toml`
@@ -81,7 +85,7 @@ mpy-cli init
 
 ### 6) 后续重配（可选）
 
-如果你后续想修改端口、同步模式、运行目录等配置，直接执行：
+如果你后续想修改端口、同步模式、运行目录、设备上传目录等配置，直接执行：
 
 ```bash
 mpy-cli config
@@ -117,6 +121,7 @@ mpy-cli deploy --no-interactive --yes
 
 ---
 
+<span id="install"></span>
 ## 在其他项目中安装为命令行工具
 
 如果你要把 `mpy-cli` 安装到另一个项目里使用，推荐在该项目自己的虚拟环境中安装：
@@ -141,6 +146,7 @@ mpy-cli init
 mpy-cli config
 mpy-cli plan
 mpy-cli deploy
+mpy-cli upload
 ```
 
 说明：
@@ -177,6 +183,12 @@ mpy-cli config
 - 无额外参数。
 - 进入交互式配置向导，更新 `.mpy-cli.toml`。
 
+常用配置项说明：
+
+- `device_upload_dir`：设备端上传目录前缀，留空表示设备根目录。
+- 当 `device_upload_dir = "apps/demo"` 时，本地 `main.py` 会上传到设备 `:apps/demo/main.py`。
+- `full` 模式会清空该上传目录，而不是整机设备根目录。
+
 ### `mpy-cli plan`
 
 ```bash
@@ -199,6 +211,34 @@ mpy-cli deploy [--mode {incremental,full}] [--port PORT] [--no-interactive] [--y
 - `--no-interactive`：禁用交互提问。
 - `--yes`：跳过执行前确认（包括全量模式二次确认）。
 
+推荐用法：
+
+```bash
+mpy-cli deploy --no-interactive --yes
+```
+
+进行 `config` 之后直接无交互烧入
+
+### `mpy-cli upload`
+
+```bash
+mpy-cli upload [--local LOCAL] [--remote REMOTE] [--port PORT] [--no-interactive] [--yes]
+```
+
+- `--local`：本地文件路径（如 `seekfree_demo/E01_demo.py`）。
+- `--remote`：设备目标路径；不传时交互模式默认与本地路径一致，可手动修改。
+- `--port`：指定设备端口。
+- `--no-interactive`：禁用交互提问；此时需显式提供 `--local` 和 `--remote`。
+- `--yes`：跳过执行前确认。
+
+推荐用法：
+
+```bash
+mpy-cli upload --local <LOCAL>
+```
+
+填写字段 `LOCAL` 指定本地文件路径之后交互式确认远程路径
+
 ---
 
 ## 常见问题
@@ -236,4 +276,4 @@ python3 -m pip install mpremote
 
 本仓库采用 GPL-3.0 协议开源，如果用于竞赛目的可酌情在赛后遵守协议。
 
-欢迎 Issue / PR / Star。
+欢迎 Issue / PR / Star。

docs/plans/2026-03-04-manual-upload-design.md

@@ -0,0 +1,83 @@
+# 手动单文件上传功能设计文档
+
+## 背景
+
+当前 `mpy-cli` 仅支持 `plan/deploy` 的计划式同步流程。对于临时上传单个脚本文件（例如 `seekfree_demo/E01_demo.py`）的场景，用户需要依赖 Git 变更或全量同步，成本较高。
+
+本设计新增独立 `upload` 命令，支持手动输入本地文件路径，并在交互中确认/修改设备目标路径。
+
+## 目标
+
+- 新增 `mpy-cli upload` 子命令，用于单文件上传。
+- 交互模式下仅通过手动输入本地文件路径，不做文件列表扫描。
+- 目标路径默认与本地输入路径一致（如 `demo/demo.py` -> 默认目标 `demo/demo.py`），允许手动修改。
+- 执行前显示上传预览并二次确认。
+- 复用现有执行链（`DeployExecutor` + `MpremoteBackend`），保持日志与错误行为一致。
+
+## 非目标
+
+- 不改变 `plan/deploy` 的现有语义与流程。
+- 不在本次支持多文件批量上传。
+- 不新增额外运行时持久化文件。
+
+## 交互与参数设计
+
+### 命令形态
+
+```bash
+mpy-cli upload [--local LOCAL] [--remote REMOTE] [--port PORT] [--no-interactive] [--yes]
+```
+
+### 参数含义
+
+- `--local`：本地文件路径。
+- `--remote`：设备相对目标路径。
+- `--port`：设备端口。
+- `--no-interactive`：禁用交互提问；缺参数时直接报错。
+- `--yes`：跳过执行前确认。
+
+### 交互流程（无对应参数时）
+
+1. 解析端口（沿用现有优先级：`--port` > 配置 > 扫描/手输）。
+2. 提示输入本地文件路径。
+3. 以本地输入路径作为默认值，提示输入设备目标路径（可直接回车）。
+4. 打印预览：端口、本地路径、最终设备路径。
+5. 确认后执行上传。
+
+## 路径与执行语义
+
+- `--remote` 或交互输入的目标路径统一作为“设备相对路径”。
+- 最终远端路径由 `device_upload_dir + remote_path` 拼接得到，与现有 `deploy` 规则一致。
+- 例：
+  - `device_upload_dir = ""`，`remote = "seekfree_demo/E01_demo.py"` -> `:seekfree_demo/E01_demo.py`
+  - `device_upload_dir = "apps/demo"`，`remote = "seekfree_demo/E01_demo.py"` -> `:apps/demo/seekfree_demo/E01_demo.py`
+
+## 校验与错误处理
+
+- 本地路径必须存在且为普通文件，否则提示并返回失败码。
+- 目标路径去空白后不能为空。
+- 非交互模式下缺失 `--local`、`--remote` 或 `--port`（且配置无法补足）时直接报错。
+- 保持 `mpremote` 不可用与执行失败的现有报错风格。
+
+## 实现边界
+
+- `mpy_cli/cli.py`：新增 `upload` 命令解析和 `_cmd_upload` 流程。
+- `mpy_cli/planner.py`：仅复用 `PlanOperation/DeployPlan` 数据结构，不新增新操作类型。
+- `mpy_cli/executor.py`：无需改动核心逻辑，复用既有 `upload` 分支执行。
+
+## 测试策略（TDD）
+
+- `tests/test_cli.py`
+  - `upload` 在交互模式下可读取本地路径并生成默认远端路径。
+  - `upload` 可接受手动修改后的远端路径。
+  - 非交互模式缺失必要参数时报错。
+  - 本地路径不存在时报错。
+- `tests/test_docs_and_ci.py`
+  - README 参数总览新增 `mpy-cli upload` 与相关参数。
+
+## 验收标准
+
+- 用户可通过 `mpy-cli upload` 独立上传单文件。
+- 用户输入 `seekfree_demo/E01_demo.py` 后，远端默认同路径并可改写。
+- 上传前有清晰预览与确认（`--yes` 可跳过）。
+- 新增测试通过且不破坏现有 `plan/deploy` 流程。