xworkmate-app/docs/howto/persistence-storage-layout.md

Persistence Storage Layout

目标

本文定义桌面端持久化层的唯一落地规则。XWorkmate.svc.plus 后续必须只认这一套目录和文件约定，不再引入 SQLite、本地 secret fallback、或第二套临时持久化路径。

存储原则

• 非敏感配置只写 settings.yaml
• 任务线程会话按 sessionKey 单文件保存
• 敏感信息只写固定 secret path
• 首次启动必须自动建目录
• 重启和升级不能主动删除配置或会话文件
• 文件写入使用临时文件后替换的原子写策略
• 磁盘路径不可用时，只允许退回内存，不再切换到另一套本地 fallback 持久化

默认目录结构

默认根目录位于应用支持目录下的 xworkmate 子目录。

macOS 示例：

~/Library/Application Support/<App Support>/xworkmate/

运行时布局：

xworkmate/
  config/
    settings.yaml
    secret-audit.json
  tasks/
    index.json
    <sessionKey-encoded>.json
  secrets/
    <key-encoded>.secret

文件职责

config/settings.yaml

• 唯一非敏感配置源
• 内容对应 SettingsSnapshot.toJson()
• 不保存 token、password、API key、device private key 等敏感字段

config/secret-audit.json

• 保存 SecretAuditEntry 列表
• 属于本地非敏感审计信息
• 最大长度由运行时控制

tasks/index.json

• 保存线程会话顺序
• 当前格式：

{
  "version": 1,
  "sessions": ["session-a", "session-b"]
}

tasks/<sessionKey-encoded>.json

• 每个线程会话一个文件
• 文件内容为 AssistantThreadRecord.toJson()
• 文件名不直接使用原始 sessionKey，而是稳定编码后的结果，避免跨平台文件名问题
• 记录内容里的 sessionKey 仍保持原值，不修改模型

secrets/<key-encoded>.secret

• 固定 secret path
• 每个 secret key 一个文件
• 保存 Gateway token、Gateway password、AI Gateway API key、Vault token、device identity、device token 等敏感信息
• 文件名使用稳定编码，避免泄露原始 key 名并规避非法字符

初始化规则

• SecureConfigStore.initialize() 必须先准备目录结构
• 不要求用户先保存一次配置，目录应在首次运行时就存在
• 如果外部显式传入测试路径覆盖，仍然遵守相同布局

清理规则

• clearAssistantLocalState() 只清理：
  • settings.yaml
  • tasks/index.json
  • tasks/*.json
• 不清理 secrets/*.secret
• 不主动清理 secret-audit.json

恢复规则

• 启动时先读 settings.yaml
• 再读 tasks/index.json 与对应 task 文件
• index.json 缺失时，允许扫描 tasks/*.json 进行恢复
• secret path 中某个 key 缺失时，只影响该 key，不应拖垮整个 store

禁止事项

• 禁止重新引入 SQLite 作为桌面持久化主存储
• 禁止把 secret 写入 SharedPreferences
• 禁止把 .env 自动导入为持久化配置
• 禁止在 secret path 不可用时偷偷切换到另一套磁盘 fallback 路径
• 禁止在升级或启动时主动删除已有配置与会话文件

测试建议

• 验证首次启动自动建目录
• 验证重启后 settings.yaml 可恢复
• 验证 tasks/<session>.json 跨实例可恢复
• 验证 clearAssistantLocalState() 不删 secrets
• 验证磁盘不可用时保留内存态，不发生崩溃