个人助理智能体不是写完就结束。
只要它长期运行，就会遇到模型变更、API 失败、服务器重启、配置漂移、磁盘满、日志爆炸、密钥过期和工具失效。维护手册的价值，是让这些问题不靠临场发挥。
日志：先能看见问题
日志至少要回答：
- 用户发了什么请求。
- 命中了哪个 Skill。
- 调用了哪些工具。
- 工具是否成功。
- 失败原因是什么。
- 是否触发人工确认。
日志不需要记录完整隐私内容和密钥，但要足够支持排查。
日志检查频率
可以分三类：
- 日常：查看错误数量和最近失败。
- 每周：检查是否有重复失败模式。
- 每月：把高频失败整理成 QPC 或修复任务。
日志如果只写不看，就没有维护价值。
备份：先备配置和记忆
个人助理最重要的资产通常不是程序本身，而是配置、密钥引用、知识库和长期记忆。
备份优先级：
- 配置文件。
- 知识库或记忆数据库。
- 自定义 Skill。
- 部署脚本。
- 关键日志样本。
密钥本身要按安全方式保存，不应该明文塞进普通仓库。
恢复演练
没有恢复演练的备份，只是心理安慰。
至少要知道：
- 新机器上如何恢复配置。
- 如何恢复知识库。
- 如何重新启动服务。
- 如何验证入口和工具调用。
- 如何回滚到上一个可用版本。
恢复流程应该写成清单。
升级：小步走
升级模型、依赖或系统服务前，先看影响范围。
建议流程：
- 记录当前版本。
- 备份配置和记忆。
- 阅读变更说明。
- 小范围验证核心任务。
- 观察日志。
- 保留回滚路径。
不要在没有备份的情况下升级关键组件。
安全检查
每月做一次轻量安全检查：
- 是否有多余开放端口。
- 面板是否仍有认证保护。
- 密钥是否泄露到日志。
- 配置文件权限是否过宽。
- 高风险工具是否仍需人工确认。
- 依赖是否有明显安全更新。
个人助理越连接真实世界，越需要定期检查边界。
人工接管流程
当系统异常时，Agent 应该知道如何停下来。
人工接管流程包括：
- 停止自动执行高风险动作。
- 保留现场日志。
- 输出当前任务状态。
- 列出已完成和未完成动作。
- 等待人工决定是否继续。
这比“自动修复一切”更可靠。
维护手册的目标
维护手册不是为了把系统变复杂，而是为了让未来的你不用猜。
一个长期可用的个人助理，必须能被重启、迁移、排错、升级和停用。否则它不是助理，而是新的负担。