让 Codex 长期维护项目：从多个项目里沉淀出的工程经验

最近一段时间，我让 Codex 参与维护了几类不同的项目：本地媒体播放器、静态博客、自托管服务、Windows 配置、网络规则，以及带有多层关联关系的数据配置。

这些项目的技术栈和风险完全不同，但最后反复验证有效的做法非常相似。

这篇文章是一次公开版复盘。为了避免暴露隐私，正文不包含真实服务器地址、本机路径、账号、令牌、私钥或私人对话细节；项目只按功能类别描述。

1. 先建立边界，再开始修改

最容易出问题的任务，通常不是代码难，而是“当前到底允许改什么”没有说清楚。

一个可靠的开始应该先回答几个问题：

• 当前所在的仓库、分支和提交是什么？
• 工作区有没有用户尚未提交的修改？
• 目标程序、服务或测试环境是否正在运行？
• 这次任务允许修改哪些文件、目录和外部系统？
• 失败后如何恢复？

因此我现在会先做只读检查：查看 Git 状态、分支、工作树、配置和运行状态，再决定是否进入写入阶段。混合工作区里不使用无边界的 git add -A，而是明确列出本次允许提交的文件。

这条规则在播放器、插件和配置项目中尤其重要：一个看似无关的未跟踪目录，可能正是用户正在进行的实验；一个正在运行的测试程序，也可能持有真实配置、缓存或日志。

2. 跨项目复用的是原则，不是整套代码

一个项目里的好做法，不能直接复制到另一个项目。

例如，媒体项目里的远程控制协议、安全边界、更新包校验可以迁移为“契约意识”；但同步观看、房间状态或插件语义属于另一个产品边界，就不应该因为文档里出现过而被带进来。

跨项目复用时，我会把信息分成三类：

1. 可迁移原则：例如配置比较、哈希校验、回滚、最小发布包。
2. 项目适配规则：需要与当前代码和测试交叉核对，不能只凭旧文档。
3. 项目专属细节：路径、端口、域名、协议字段和业务状态只留在原项目。

这样做的结果不是“复制更多”，而是让当前项目只吸收真正适用的知识。

3. 发布物必须有明确契约

在桌面程序和嵌入式运行环境中，发布一个压缩包不等于完成发布。真正重要的是：这个包应该包含什么、不应该包含什么，以及更新器是否接受同一套定义。

我后来把发布流程收敛为一份可检查的契约：

• 入口、配置模板、许可证和依赖是否齐全；
• 运行时模块是否完整；
• README、开发脚本、测试文件和源协议是否被意外带入；
• 更新器的解包 allowlist 是否和打包器一致；
• ZIP 成员、文件数量、大小和 SHA-256 是否符合预期。

打包器和更新器只要有一边采用了不同的文件范围，就会出现“本地构建通过、用户更新后却不是同一个版本”的问题。

还有一个容易误判的地方：推送分支不一定会更新用户实际下载的发布渠道。比如更新器如果固定下载 Latest Release，那么分支上的新提交并不会自动改变 Latest。分支、构建产物和 Release 必须分别验证。

4. 把验证分成不同层级

“测试通过”不是一个足够精确的结论。不同项目中，我会把验证至少分成五层：

层级	它能证明什么	它不能证明什么
静态检查	类型、Schema、格式和基本结构正确	真实运行时一定正常
构建或打包	产物能生成，成员和资源可审计	用户环境、网络和客户端行为
本地运行	当前机器上的最小流程可用	生产域名、证书和外部链路
真实客户端	用户界面、播放、交互确实可用	其他版本和其他机器一定相同
生产验收	DNS、代理、HTTPS、页面或服务实际可达	已经满足所有合规要求

静态博客可以通过 check 和 build，但还要验证生成的 RSS、Sitemap、404、手机布局和草稿过滤。播放器的单元测试通过，也不能替代真实客户端播放和控制测试。服务器返回 HTTPS 200，也不能直接推导出备案或其他合规状态。

把验证边界说清楚，比笼统地说“没问题”更有用。

5. 排查问题时比较路径，而不是猜原因

网络问题尤其容易被错误信息带偏。一个页面返回 502，可能是上游端口错误；一个公网请求返回 403，可能在到达服务器之前就被云端拦截；本机代理的 Fake-IP 也可能让 DNS 和 TLS 看起来与真实网络完全不同。

比较已知正常和异常的路径，通常比反复重试更快：

• DNS 是否解析到同一目标？
• 请求是否真正到达 OpenResty/Nginx？
• 代理使用的协议、端口和 SNI 是否正确？
• 上游服务是否在监听，还是只启动了容器但没有暴露端口？
• 失败发生在客户端、代理、云端拦截还是源站？

只有把链路分段，才能知道应该改客户端、反向代理、服务监听，还是等待外部状态变化。

6. 保护真实状态，部署使用可回滚切换

配置、缓存、日志和证书不应该因为一次代码同步被覆盖。尤其是测试环境和生产环境，运行时状态往往比源代码更难重新获得。

现在更稳妥的同步方式是：

1. 检查进程和目标目录；
2. 备份真实配置与当前版本；
3. 上传到临时目录；
4. 校验压缩包或文件的 SHA-256；
5. 在临时目录解压并检查文件数量、关键文件和权限；
6. 将旧目录改名为带时间戳的回滚目录；
7. 把新目录切换为活动目录；
8. 验收通过后再清理临时文件。

静态博客部署也是同样的思路：先构建 dist/，再校验包，保留旧站点目录，最后原子切换。这样即使新版本有问题，也有清楚的恢复路径，而不是在生产目录里边改边猜。

7. 配置和数据要沿着关系链验证

配置文件“格式正确”不代表业务正确。

在网络规则项目中，层级关系比单个字段更重要：业务策略组、地区策略组和具体节点必须保持正确的父子关系。修改后要比较版本差异，并检查原有直连、兜底和特殊规则是否仍然存在。

在数据配置项目中，也不能只看 Excel 能否打开。需要沿着“表格 → 中间配置 → 运行时配置”的链路核对 ID、类型、时长、公式和边界值，并对关键结果做独立复算。

通用方法是：先写清楚字段关系和约束，再做修改，最后从输入重新推导输出。这样能避免只对着最终文件做表面检查。

8. 隐私和安全是交付的一部分

AI Agent 能看到的内容很多，因此“不要把秘密放进输出”必须成为流程，而不是临时提醒。

公开文档和博客中不应该出现：

• API key、密码、Cookie、Bearer token 和私钥；
• SSH 配置、证书私钥和完整服务器清单；
• 含授权参数的临时链接；
• 不必要的本机用户名、完整路径和内部端口拓扑；
• 能直接关联到私人对话或个人数据的原始日志。

需要操作凭据时，让用户在本地或密钥管理器中输入；需要写经验文章时，只保留可迁移的判断和验证方法。技术细节越具体，越要先问自己：它是否真的帮助读者，还是只是增加了泄露面？

9. 失败记录比成功截图更有价值

多个项目里最值得保留的内容，往往是“当时为什么不能这样做”：

• 依赖冲突时，不用 --force 掩盖版本问题；
• 快照恢复工具的名字，不代表它真的恢复整台机器；
• 分支推送成功，不代表另一个下载渠道已经更新；
• 预热动作触发了缓存，不代表首帧时间一定下降；
• 更大的播放器缓存不一定更好，内存较小的设备需要保守默认值；
• 批量改域名必须先确认是“新增并保留旧域名”还是“替换并删除旧域名”。

把失败原因写下来，下一次 Agent 就不必重复走同一条弯路。好的维护文档不是“永远成功”的宣传，而是包含边界、失败模式和停止条件的操作说明。

10. 一份适合长期协作的检查表

修改前

• 确认仓库、分支、提交和工作区状态
• 读取项目规则、README 和相关配置
• 列出允许修改的文件和外部系统
• 确认当前运行状态、备份位置和回滚方案

修改后

• 执行最相关的单元测试、静态检查或数据复算
• 检查差异范围，没有混入无关文件
• 对产物做成员、大小和哈希审计
• 区分本地验证、真实客户端验证和生产验证

发布或部署前

• 给出变更范围、风险、包哈希和回滚路径
• 明确分支、构建产物、Release 和线上版本是否一致
• 使用临时目录和原子切换，不直接覆盖唯一原件
• 验证页面、服务、日志和外部链路
• 清理临时文件，但保留可恢复的备份

结语

让 Codex 长期维护项目，关键不是让 Agent 记住更多代码，而是让项目拥有更好的上下文：清楚的边界、稳定的目录、可重复的检查、明确的发布契约和诚实的验证结论。

当这些信息都写进仓库和维护流程后，AI 的角色就不只是“生成一段代码”，而是能够在较长时间里持续理解、修改、验证和交付一个真实项目。