# 安装、升级与排障

## 最短检查顺序

1. `python setup.py --doctor --json`：查看解释器、依赖、来源是否配置以及最近记录的插件加载版本。此命令不采集、不读正文、不创建数据目录；回执版本仅是最近一次加载记录，不证明 DSH 当前仍在运行。
2. 在 DSH 调用 `wechat_status`，检查是否绑定来源及 `stage_one_coverage`。
3. 需要新记录时先调用无参数 `wechat_refresh`；成功后用带时间和会话筛选的 `wechat_review` 读取。

## 常见情况

| 现象 | 处理 |
| --- | --- |
| cannot resolve profile bundle | 安装包含 package.json 的目录；确认目录完整。DSH 0.2.0-rc.2 首次添加本地目录后，保存任务再完整重开；页面刷新不能保证重新解析 |
| 缺少依赖 | 显式运行 `安装采集依赖.cmd`；工具不会自行联网安装 |
| 多个账号 | 在本机运行 `python setup.py --choose-account`；不要让模型猜账号 |
| NOT_INDEXED | 单独运行 `python setup.py` 或调用 `wechat_prepare`；第二步不会暗中采集 |
| PARTIAL / UNKNOWN | 检查本机绑定的来源是否本身只有部分记录或缺少快照时间；重复刷新同一局部文件不能补齐历史 |
| 今天为空、时间止于昨天 | 检查覆盖时间，再显式刷新。手机未同步的记录不能由电脑快照证明为空 |
| 分页 INVALID_CURSOR | 索引或忽略名单可能已经更新；保持原范围，从第一页重新读取 |
| Auto 仍弹窗 | 插件仅去掉重复确认；宿主风险审阅仍可能转人工，保存待办和修改偏好也独立确认 |
| 采集失败 / 超时 | 保留原快照与索引，查看固定错误码；详细本机日志不可公开上传 |

诊断的“当前 Python 缺依赖”只针对执行诊断的解释器。原生采集还会寻找私有采集环境；已经有该环境时不能仅凭这一条断言采集不可用。

## 升级与回退

保留已安装的插件目录和私有状态。结束本次微信查询后替换源码，再使用宿主正式加载流程；不要删除 profile、清空索引或中断其他任务。磁盘新版本和运行中版本不同是正常的待重载状态。0.5.0 保持 0.4.0 的工具名称及两阶段接口，没有强制数据迁移。

升级前应自行备份私有状态与原始导出。若索引连接正在写入，先结束该微信操作再复制整个状态目录，避免只复制一个 SQLite 文件而漏掉 WAL。旧版运行和新版本代码不要同时写同一状态。

回退时恢复前一个完整源码包并正常重载，不删除当前资料。重新安装路径或修改 `stateDirectory` 时务必使用同一私有目录；更换目录不会自动迁移数据。

## 日常运行

```text
python setup.py --refresh --json
python setup.py --review --start-date 2026-01-01 --end-date 2026-01-01 --kind group --limit 100 --json
python collector/open_latest.py --output <私有采集输出根目录>
```

需要每天执行时，可将第一条命令放入你已有的本机任务计划；脚本不安装定时任务、不自动打开或登录微信。命令行入口无交互暂停，双击中文 CMD 入口会保留窗口供查看结果。