2.2 KiB
2.2 KiB
ADR-0005：页面内目录浏览器
- 状态：已接受（取代早期"后端弹出系统对话框"方案）
- 日期：2026-10-24
背景
任务的工作目录必须是绝对 Windows 路径。浏览器的文件选择控件出于安全限制只暴露文件名或伪造路径，拿不到用户所选目录的真实绝对路径。
最初尝试由后端调用 IFileOpenDialog 弹出系统文件夹对话框，但代价明显：需要新增 windows crate；对话框属于后端进程而不属于浏览器窗口，可能被浏览器挡住；接口会长时间挂起；自动化测试无法覆盖。对于一个本机 Web 应用，这些都不划算。
决策
- 在页面内实现目录浏览器：
DirectoryPickerDialog弹窗，盘符 → 逐级进入 → 「使用此目录」。 - 后端只提供只读列表接口
GET /api/v1/system/directories?path=<绝对路径>，路径为空时返回盘符。 - 响应包含
path（当前目录）、parent（上一级，盘符根为 null）、entries（仅子文件夹，按名称排序）、truncated（超过 500 项）。 - 弹窗顶部保留可编辑的路径输入框，支持直接粘贴绝对路径后回车跳转；「上一级」「盘符」用于层级导航。
- 选中结果通过
setValue回填输入框并触发虚拟环境重新探测；输入框始终可编辑，二者不互斥。 - 列表接口是只读的，与任务列表一样免令牌；不存在的路径返回
400 DIRECTORY_NOT_FOUND，相对路径返回400 DIRECTORY_PATH_INVALID，无权限返回400 DIRECTORY_UNREADABLE。
原因
- 纯前端就能完成交互，不依赖桌面会话，Windows 服务模式下同样可用。
- 不引入新依赖，也不需要 COM 线程管理。
- 弹窗属于页面本身，不会被浏览器遮挡，焦点和键盘行为可控。
- 可以被 Vitest 和 Playwright 完整覆盖。
边界
- 只列文件夹，不列文件；隐藏目录（如
.venv）会正常显示，便于选择虚拟环境目录。 - 目录读取失败时停留在原目录并提示原因，不做静默降级。
- 单个目录最多返回 500 个子文件夹，超出时提示截断。
- 列表接口只做只读列举；真正执行脚本时仍需任务配置中的绝对路径通过后端校验。