DSH 将每个会话存储为一个目录，其中包含每个格式生成的单个不可变文件。升级到 0.1.5 后，迁移的最终步骤是一个封闭式词汇审计：每条消息必须携带 source.kind，且该值必须来自一个固定的 15 个值集合。任何过时的值都会导致整个迁移中止，从而使会话无法打开。即便会话列表正常显示，点击打开时也会收到通用的 gateway/internal 错误。
dsh-sessions-diagnosis 插件通过在 CLI、代理工具或 DSH Web UI 中运行 DSH 官方的迁移链，来解决这一问题。
核心功能¶
该插件提供三种核心能力：
- 诊断：运行 DSH 发布的官方迁移链，报告的原因与 Harness 实际遇到的完全一致。它会将每个会话分类为
ok、unmigrated、repairable、unrepairable等，并指出具体的错误字段。 - 修复：生成有效的当前格式后继者。原始文件不会被修改。当 DSH 的 codec 无法访问时，如果规则匹配，会进行原地修复（带字节级备份且可撤销）。
- 可视化：在 DSH Web UI 的 Settings → Session diagnosis 中提供仪表板。显示所有会话的判定结果、原因，并提供预览修复步骤的“一键修复”功能。
安装与启用¶
使用官方安装命令将插件添加到 Web Profile：
dsh plugin --profile web add github:YouHui1/dsh-sessions-diagnosis
该命令会下载预构建的 JavaScript，无需构建步骤或依赖安装。安装后，重启 DSH 并刷新浏览器。仪表板将出现在 Settings → Session diagnosis 中。
典型用法¶
插件提供了一个名为 dsh-session-doctor 的命令行工具。
扫描与诊断¶
# 查看会话存储中的内容
dsh-session-doctor scan
# 对所有会话进行分类诊断
dsh-session-doctor diagnose
# 诊断特定会话的详情
dsh-session-doctor diagnose <id>
修复会话¶
# 对特定会话进行试运行（不写入任何内容）
dsh-session-doctor repair <id>
# 执行修复
dsh-session-doctor repair <id> --apply
# 修复所有可修复的会话
dsh-session-doctor repair --all --apply
# 撤销本次工具进行的修复
dsh-session-doctor rollback <id>
# 使用 DSH 的 codec 验证所有会话
dsh-session-doctor verify
测试与演练¶
# 创建一个模拟的损坏会话（低风险规则：过时的 source.kind）
dsh-session-doctor demo
# 创建一个模拟的损坏会话（中风险规则：过时的描述符版本）
dsh-session-doctor demo --scenario descriptor
# 删除演示会话
dsh-session-doctor demo --remove --apply
注意：demo 命令写入一个伪造的损坏会话，该会话不会进入你的真实会话存储。它使用默认的 <tmp>/dsh-session-doctor-demo 作为存储目录，并拒绝 --root 指向真实存储的命令。
适用场景与注意事项¶
- 无需重启：修复会话不需要重启 DSH，DSH 会在打开时解析世代，修复后的会话在下一次点击时即可打开。
- 数据安全：原始文件从未被修改。演示会话被隔离在独立存储中，不会污染你的会话列表。
- 生态背景：该插件遵循 DSH “一切皆插件”的理念，通过 Cordis patch 机制集成。安装前建议检查源码与许可证（MIT）。
总结¶
dsh-sessions-diagnosis 是一套针对 DSH 升级后会话迁移问题的诊断与修复工具。它提供了 CLI 和 Web UI 两种操作方式，通过复用 DSH 官方逻辑而非猜测，确保了修复的准确性。
