数据维护

维护命令会操作某个 Profile 的持久状态。开始前先备份，并优先使用不覆盖原文件或 Dry Run 的模式。

操作前检查

anyy backup create
anyy gateway status

离线写入命令需要取得 Profile 的独占所有权。提示 Profile 正在使用时，不要绕过锁；有常驻维护入口就使用该入口，否则停止这个 Profile 的 Gateway。

常驻 Runtime 的自动清理

Gateway 会在启动时、此后每 24 小时，以及 Object Store 发出清理信号时，执行一次有批量上限的 Semantic Maintenance。它负责：

• 释放已经交付给 Parent Session 的 Inbox Payload；
• 清理超过保留期的临时 Audit Receipt 与 Pending Artifact；
• 释放已经失效的 Execution Recovery 数据；
• 回收没有引用的 Content-addressed Objects；
• Checkpoint SQLite，并逐步回收空闲 Page。

该流程不会把 Canonical Conversation Transcript、Memory 文件、已经 Bound/Pinned 的 Artifact、Workspace 文件或仍有 Owner 的 Evidence 当作清理目标。存储写满后的恢复路径可以丢弃可重建的 Lexical Search Cache，但 Canonical Record 仍保留，可用于重新建立索引。

anyy status --json 的 storage 部分会显示上次自动维护与 Pending Cleanup 数量。这套日常 Housekeeping 和下面需要用户手工运行的数据库副本、Token Cache 命令不是同一件事。

Checkpoint 状态数据库

anyy maintenance checkpoint-state

该操作把 SQLite WAL 中的内容 Checkpoint 到主数据库，需要离线 Profile 所有权。

只有支持的备份方式不适用、必须复制原始数据库文件时，才需要先做这一步。日常保护 Profile 仍应使用 anyy backup create。

生成压缩副本

更安全的方式是写出新数据库，不替换原文件：

anyy maintenance compact-state --output /secure/path/state.compact.db

确认副本和备份都正常后，才考虑原位替换：

anyy maintenance compact-state --replace

--replace 要求 Gateway 已停止并取得独占所有权；它不能和 --output 同时使用。只有默认临时目录空间不足时才指定 --temp-dir。

验证完成前保留备份

替换数据库后，先运行 anyy status 与 anyy doctor，确认无误再清理备份或压缩副本。

补全缺失的 Token 估算

先只预览，不修改数据库：

anyy maintenance cache-token-estimates

确认候选数量后再写入：

anyy maintenance cache-token-estimates --execute

它只补全尚无正数 Token Count 的消息，不会覆盖已有正数。--limit N 可限制候选数量，--json 便于保存结果。Execute 模式需要离线所有权；Dry Run 只读打开已有数据库，也不会创建缺失的数据库。

安全操作顺序

1. 创建 Profile 备份；
2. 如果命令需要离线所有权，停止正确的 Gateway；
3. 先运行不覆盖原文件或 Dry Run 版本；
4. 核对输出中的路径与数量；
5. 确实需要时再执行写入；
6. 启动 Gateway，并检查 status 和 doctor。

常见问题

现象	处理方法
Profile 所有权冲突	停止准确对应的 Gateway 后重试
无法生成压缩副本	检查目标目录权限和剩余空间
--replace 被拒绝	去掉 --output，停止 Gateway，并确保已有备份
Token Dry Run 没有候选	当前保留消息都已有正数估算
自动维护报告错误	查看 anyy status --json；空间不足先释放容量，再检查经过脱敏的 Gateway Log