docs: define portable directory defaults

2026-07-27 23:50:24 +08:00
parent cab7e6ac7b
commit 92091a6690
10 changed files with 70 additions and 9 deletions
@@ -97,10 +97,17 @@ type TrayState struct {
 func DefaultPath() (string, error) // <dir(os.Executable())>\\config.json
 func LegacyPath() (string, error)  // %APPDATA%\\chub\\config.json，仅用于一次迁移
 func OpenDefault() (*Store, error) // 目标优先；必要时校验并原子迁移 legacy
-func DefaultInstanceUserDataDir(instanceID string) (string, error) // <dir(os.Executable())>\\user_data_dirs\\<instanceID>
+type PortableDirectoryDefaults struct {
+    UserDataDir string // <dir(os.Executable())>\\user_data_dirs
+    LogDir      string // <dir(os.Executable())>\\logs
+}
+
+func ResolvePortableDirectoryDefaults() (PortableDirectoryDefaults, error)
+func DefaultInstanceUserDataDir(defaultRoot, instanceName, instanceID string) (string, error) // <root>\\instance-<safe-name>-<short-id>
+func PrepareInstanceUserDataDir(ctx context.Context, dir string) error
 ```

-调用方不得把当前工作目录作为配置来源，也不得自行复制、删除或合并 legacy 文件。`OpenDefault` 的迁移是文件级配置迁移，不迁移 `UserDataDir`、日志目录或浏览器文件；目标文件存在、legacy 缺失时均不产生写入。`DefaultInstanceUserDataDir` 只生成绝对默认字符串，不创建目录；调用方必须先分配稳定、唯一的实例 ID。迁移失败返回稳定的配置错误，调用方不得改用 legacy 继续写入。
+调用方不得把当前工作目录作为配置来源，也不得自行复制、删除或合并 legacy 文件。`OpenDefault` 的迁移是文件级配置迁移，不迁移已有实例 `UserDataDir` 或浏览器文件；目标文件存在、legacy 缺失时均不产生写入。目录模式为 portable 时必须每次通过 `ResolvePortableDirectoryDefaults` 从实际 exe 位置重新解析，custom 时只接受用户显式选择的绝对路径。`DefaultInstanceUserDataDir` 只生成绝对默认字符串，不创建目录；调用方必须先验证实例名称唯一并分配稳定 ID。`PrepareInstanceUserDataDir` 只能在后台调用，负责安全创建/写入预检，失败时不得启动浏览器。迁移失败返回稳定的配置错误，调用方不得改用 legacy 继续写入。

 ## CLI 当前合约