# ADR-0005：页面内目录浏览器

- 状态：已接受（取代早期"后端弹出系统对话框"方案）
- 日期：2026-10-24

## 背景

任务的工作目录必须是绝对 Windows 路径。浏览器的文件选择控件出于安全限制只暴露文件名或伪造路径，拿不到用户所选目录的真实绝对路径。

最初尝试由后端调用 `IFileOpenDialog` 弹出系统文件夹对话框，但代价明显：需要新增 `windows` crate；对话框属于后端进程而不属于浏览器窗口，可能被浏览器挡住；接口会长时间挂起；自动化测试无法覆盖。对于一个本机 Web 应用，这些都不划算。

## 决策

1. 在页面内实现目录浏览器：`DirectoryPickerDialog` 弹窗，盘符 → 逐级进入 → 「使用此目录」。
2. 后端只提供只读列表接口 `GET /api/v1/system/directories?path=<绝对路径>`，路径为空时返回盘符。
3. 响应包含 `path`（当前目录）、`parent`（上一级，盘符根为 null）、`entries`（仅子文件夹，按名称排序）、`truncated`（超过 500 项）。
4. 弹窗顶部保留可编辑的路径输入框，支持直接粘贴绝对路径后回车跳转；「上一级」「盘符」用于层级导航。
5. 选中结果通过 `setValue` 回填输入框并触发虚拟环境重新探测；输入框始终可编辑，二者不互斥。
6. 列表接口是只读的，与任务列表一样免令牌；不存在的路径返回 `400 DIRECTORY_NOT_FOUND`，相对路径返回 `400 DIRECTORY_PATH_INVALID`，无权限返回 `400 DIRECTORY_UNREADABLE`。

## 原因

- 纯前端就能完成交互，不依赖桌面会话，Windows 服务模式下同样可用。
- 不引入新依赖，也不需要 COM 线程管理。
- 弹窗属于页面本身，不会被浏览器遮挡，焦点和键盘行为可控。
- 可以被 Vitest 和 Playwright 完整覆盖。

## 边界

- 只列文件夹，不列文件；隐藏目录（如 `.venv`）会正常显示，便于选择虚拟环境目录。
- 目录读取失败时停留在原目录并提示原因，不做静默降级。
- 单个目录最多返回 500 个子文件夹，超出时提示截断。
- 列表接口只做只读列举；真正执行脚本时仍需任务配置中的绝对路径通过后端校验。