如果同时使用 Web profile：

dsh plugin --profile web update @danglong0313/dsh-history-sync

卸载：

```powershell
dsh plugin --profile desktop remove @danglong0313/dsh-history-sync

## 在 DSH 设置中配置

安装并启动 DSH 后，打开：

```text
设置 → 插件 → 插件配置 → History Sync

这里可以直接选择 Codex/Claude 来源、最近天数、单次任务上限、工作目录过滤、项目分组、允许实际导入和自动同步。点击“保存并应用”后无需重启 DSH；开启“自动同步”会同时退出预览模式、立即启动一次同步，并在同步完成后自动刷新左侧项目栏。

界面配置作为插件自有覆盖层保存在 stateDirectory/settings.json；同步游标和去重状态仍单独保存在 stateDirectory/state.json。两者都不会写入 cordis.patch.yml，也不会包含消息正文或密钥。卸载插件不会自动删除这些运行数据。

高级配置与完整 patch 覆盖

普通设置请优先使用界面。部署级参数（Codex 命令、协议分页、超时、状态目录和消息纳入策略）仍可通过 profile patch 配置。DSH patch 对同一 ID 的 config 是整项替换，不是深度合并，因此覆盖时必须重述完整配置：

- id: history-sync
  name: '@danglong0313/dsh-history-sync'
  config:
    codexEnabled: true
    claudeEnabled: true
    autoSync: false
    syncIntervalMinutes: 60
    importDays: 30
    maxSessionsPerSync: 50
    workspaceRoots: []
    groupByWorkspace: true
    readOnly: true
    previewOnly: true
    stateDirectory: !!js dshHomePath('history-sync')
    codexCommand: auto
    codexArgs:
      - app-server
    codexPageSize: 100
    codexRequestTimeoutMs: 30000
    codexShutdownTimeoutMs: 3000
    codexSourceKinds:
      - cli
      - vscode
      - appServer
    claudePageSize: 100
    claudeIncludeSystemMessages: false
    claudeIncludeWorktrees: true
    claudeIncludeProgrammatic: true

字段说明：

• codexEnabled / claudeEnabled：启用对应来源，至少开启一个。
• importDays：只考虑最近 N 天，默认 30，不会无限扫描全部历史。
• maxSessionsPerSync：两种来源合并排序后，单次最多处理的任务数。
• workspaceRoots：可选绝对目录列表；任务工作目录必须等于或位于其中一个目录下。
• groupByWorkspace：为现存的原工作目录创建或复用 DSH Workspace，并把镜像 Session 加入对应项目分组。
• readOnly：v1 必须为 true；配置为 false 会在插件加载时失败。
• previewOnly：为 true 时拒绝实际导入。
• stateDirectory：插件自有界面设置、同步游标、fingerprint、pending 写前记录和 generation 状态目录；消息正文不写入这里。
• codexSourceKinds 默认只纳入交互式主任务（cli、vscode、appServer）。exec、subAgent* 和 unknown 容易包含自动化、子代理提示词或协议消息，只有明确需要时才应手动加入。
• codexCommand: auto：先使用 DSH_HISTORY_SYNC_CODEX，再查找 PATH；Windows 下还会通过 AppX 注册信息自动定位 Codex Desktop 内置的官方 codex.exe。由于 WindowsApps ACL 会阻止普通 DSH 子进程直接启动该路径，插件会把同一官方二进制缓存到 stateDirectory/codex-bin 后运行；也可改为官方可执行文件的绝对路径。
• 其余 Codex/Claude 字段控制官方客户端分页、超时和纳入的公开来源类型。

默认只镜像用户可见的用户文本和助手文本。Codex 的 system/developer 消息、reasoning、工具调用、审批和命令输出不会伪装成聊天消息；Claude 的 system、thinking、tool use/result，以及以 、、`` 等 XML 风格控制标签开头的记录也会跳过。不完整且尚无助手回复的上游 turn 会等到完成后再导入。

界面只暴露日常、安全的字段；保存时会原子写入并立即校验。错误配置会明确拒绝，例如两个来源均关闭、相对工作目录、关闭只读模式，或在仍为预览模式时开启自动同步。