AI 助手 05：写迭代博客时，先把事实和路线图分开

给持续迭代的项目写博客，最容易发生的偏差不是文章不够长，而是把“准备做”写成“已经做”。这次整理 AI-assistant 项目页时，我重新检查了 V0/V1 的代码、启动手册和版本路线图，并把项目内容分成三层：已验证事实、明确风险、后续计划。

这个划分也会成为后续项目文章的写作规则。

第一层：只写能在代码或验收里找到的事实

当前可以写成成果的内容，必须至少满足一个条件：仓库中已有实现、可以通过明确接口验证，或者有可重复执行的启动与测试路径。

对 ai-study 来说，下面这些是事实：Docker Compose 能编排基础依赖和三层应用；Java 有会话、消息和调用日志；Python 有 demo 与 OpenAI 兼容 provider；前端能创建会话、发送同步消息并查看调用信息；健康检查会区分进程存活与依赖就绪。

因此文章可以给出实际路径，例如：

docker compose up -d --build
Invoke-RestMethod http://localhost:8080/api/health/python

读者能够复查，未来的我也能复跑。相比“系统已经具备企业级高可用能力”这类泛化判断，事实层的表达更慢一点，却不容易失真。

第二层：风险不是自我否定，而是接口边界

风险区不应该只写“后续继续优化”。它要准确说明：什么还没完成、当前为什么不能承诺、下一次实现时要验证什么。

这次页面里保留了四类风险：正式认证尚未接入，开发默认上下文不能进入生产；当前 SSE 还不是真实模型 token 流；数据库事务无法天然包住外部模型调用；RAG 权限过滤必须在检索链路中落实，而不是让提示词承担安全职责。

这些内容并没有削弱项目，反而定义了下一轮迭代的验收条件。比如真正接入流式模型时，需要验证首 token 延迟、浏览器断开、半段回复的持久化和调用日志收尾；如果这些条件没有处理完，就不把“流式聊天”标为已完成。

第三层：路线图只描述方向和验收目标

路线图可以写 RAG、Agent、评测、多模型网关，但必须使用未来时态，并且配套可检查的交付物。V2 的目标不是“学习一下 RAG”，而是文档上传、解析、分段、向量化、检索问答和引用来源；V4 的 Agent 也不是“接入 Function Calling”，而是工具 schema、调用日志和高风险操作人工确认。

这样写有两个好处：一是计划不会反过来污染当前状态；二是下一次真正开发时，博客不必从空白构思，可以直接从路线图里提取范围和验收标准。

文章和项目页都使用同一套判断

项目页偏摘要，文章偏过程，但两者应使用同一条证据链：README、接口、配置、数据表、测试或实际演示。若项目页写 V1 已完成、文章却承认前端没有真实流式，这并不矛盾——它表示 V1 的同步闭环已完成，而真正的流式属于未关闭的子问题。

我之后会保持这个顺序：先读本次改动和验收结果，再选择一个可复用的工程判断写成文章，最后同步项目页。这样写作不再是开发结束后的装饰，而是用来校正项目认知的一部分。

对一个长期作品集项目来说，能清楚说出“已经做到什么、还差什么、接下来怎么验证”，比列出更多流行名词更重要。