谈谈项目文档和代码不同步这件小事

前两天想改点东西，打开文档一看，发现文档里写的和代码完全是两回事。

配置说是从环境变量读的，代码里早改成从数据库读了。集合名写的 blog_posts，实际代码里是 post_vectors。还有那个 MCP 认证改造计划，文档里写着"待审核"，代码里 OAuth 2.0 早就上线了。

这种事情其实挺常见的，项目在不停迭代，文档很容易就落下了。

具体有哪些不同步

我花了点时间把文档和代码过了一遍，主要问题集中在几个方面：

配置管理变了。最早 AI 服务和 Qdrant 的配置都是写在 .env 里的，后来都迁移到了数据库的 tb_config 表，通过管理后台配置就行。但文档里还是旧的写法，只说"已迁移"，具体怎么读、回退机制是什么都没写清楚。

集合名变了。Qdrant 的集合从 blog_posts 改成了 post_vectors，向量 ID 也从字符串格式 ${postId}_${chunkIndex} 改成了整数 postId * 100000 + chunkIndex。文档里全是旧的。

MCP 认证已经完成改造。后端规范里还保留着一大段"改造计划"，包括迁移步骤、预计工作量什么的。实际上 OAuth 2.0 认证早就实现了，那段计划内容可以直接删掉了。

目录结构过时。代码里多了 ai-config.ts、vector-db-config.ts、react-agent.ts 这些文件，services/ai/tools/ 和 services/ai/rag/ 目录也早就建了，文档目录树里完全没体现。

聊天系统工具数量。设计文档里写的"当前实现 1 个工具"，实际上已经有 3 个了——search_articles、search_posts_meta、search_collection。

说白了就是逐个文件对比，以代码为准。一共改了 10 个文档文件。

向量化相关的文档改得最多，因为集合名、配置读取方式、向量 ID 格式都变了。后端规范主要是删掉那段过时的 MCP 改造计划，改成"已完成"的状态说明。目录结构基本重写了一遍，把实际代码里新增的文件和目录都补上了。

环境变量文档补充了 AI 配置的场景说明和 Anthropic SDK 的例外情况——说实话这个例外我之前都没注意到，client.ts 里还是直接读 process.env.ANTHROPIC_AUTH_TOKEN，和数据库配置走的是两条路。

说到底就是两个问题：一是改代码的时候没有同步改文档，二是缺少一个定期校对的机制。

代码是真理，文档是注释。注释会撒谎，代码不会。

以后改架构或者迁移配置这种事，改完代码顺手把文档也更新了，别想着"以后再补"，大概率不会补的。

这次花了大概一两个小时全部校对完，比我想象的要久。不过校对完之后，看着文档和代码终于一致了，心里还是舒服的。