cdp_hub/docs/tasks/T-407.md

---
id: T-407
title: 便携默认目录、实例名称唯一与启动目录预检
phase: 4
deps: [T-403, T-404, T-405]
status: DONE
created: 2026-07-27
owner: codex
---

## 需求与背景

复制 `chub.exe` 后，设置默认目录与新建实例默认 profile 必须跟随实际程序位置，而非快捷方式或终端当前工作目录。当前新建默认路径使用稳定 ID，缺少用户可读名称、名称唯一约束和启动前目录可写预检；程序目录受保护时 Edge/Chrome 可能在创建 profile 后立即退出，用户只能看到泛化退出提示。

## 方案与边界

- 定义“程序目录”为 `filepath.Dir(os.Executable())`。portable 默认 User Data Dir 与日志目录分别为 `<exe-dir>\\user_data_dirs`、`<exe-dir>\\logs`；不得使用 `os.Getwd()`。设置为每个目录持久化 portable/custom 来源：portable 随实际 exe 在下次启动重新解析，custom 为用户显式选择的绝对路径。旧空值及历史内置默认迁移 portable，其他非空值保留 custom；不移动既有实例目录或日志文件。
- 设置页路径字段展示实际解析路径与“跟随程序目录”说明，保留目录选择，并增加“恢复程序目录默认”。修改默认 User Data Dir 只影响后续新建实例；修改日志目录只影响后续日志写入。UI 不执行目录 I/O。
- 新建/编辑实例在提交时检查名称：去首尾空白，Windows 大小写无关唯一，并在安全化目录名后再检查冲突。重复或无效名称显示字段级“实例名称已存在，请更换”或对应修复说明，保留输入并聚焦名称。配置存储同样复核，防御手工 JSON 或并发写入。
- 新实例先分配稳定 ID；默认目录为 `<default-dir>\\instance-<safe-name>-<short-id>`。安全化处理 Windows 非法字符、保留设备名、尾部空格/句点与最大路径长度；编辑改名绝不重命名或复制现有 profile。用户仍可在停止实例时选择其他绝对目录。
- `InstanceDataPreparer` 在后台启动 adapter 中创建目标目录并验证可写；失败时不调用浏览器 launcher，返回稳定且无敏感信息的错误，UI 保留实例设置并给出“选择可写目录”的恢复提示。日志目录同样由后台/启动协调层创建与验证；不允许静默回退到当前工作目录。
- 本任务不实现目录迁移、已有实例 profile 重命名、按名称接管外部浏览器、全盘目录扫描或目录权限提升；不记录代理、Cookie、Token 或认证信息。

## 验收要点

- 自动化：覆盖 portable/custom 目录解析、历史设置迁移、实际 exe 目录而非 cwd、默认实例目录安全化/稳定 ID、Windows 保留名/非法字符/尾部句点/长路径、名称大小写重复和安全化冲突、编辑排除自身、config 边界重复拒绝、后台目录创建/不可写/取消与启动前拒绝。`go test ./...`、`go test -race ./cmd/chub ./internal/ui ./internal/platform/config ./internal/platform/files`、`go vet ./...`、`cmd /c build.bat` 通过。
- Windows smoke：将 exe 放入可写临时目录后，设置默认路径显示该 exe 同级 `user_data_dirs`/`logs`；快捷方式不同工作目录不改变结果。新建“审核 Edge”生成可读且独立的目录；重名、非法名称和受保护目录均在启动前给出可恢复提示，且 Edge/Chrome 不会被拉起。改名不移动既有 profile；选择自定义目录后仅新建实例使用它。
- 交互与无障碍：字段 Label、帮助、错误和恢复操作可用 Tab、Space/Enter 完成；错误不只用颜色，提交失败保留表单和输入法状态。窄窗口、200% 缩放、长中文名称、高对比度和浅/深色下路径与按钮重排可读。

## 执行记录

- 状态：DONE
- 变更：配置保存 portable/custom 目录来源，并按实际 `chub.exe` 同级目录解析 `user_data_dirs` 与 `logs`；历史内置目录安全迁移 portable。设置页展示来源、支持目录选择与“恢复程序目录默认”，日志目录会在后台创建、探测并写入 `chub.log`，不回退 cwd。新建默认目录改为 `instance-<安全实例名>-<短 ID>`；新建/编辑和配置存储均校验名称的 Windows 安全性及大小写无关唯一性。启动 adapter 在 launcher 前创建并验证指定 User Data Dir 可写，失败时不启动浏览器。
- 验证：`go test ./...`、`go vet ./...`、`go test -race ./cmd/chub ./internal/ui ./internal/platform/config ./internal/platform/files`、`cmd /c build.bat` 均通过。
- 阻塞：无。