AI 助手 04：别用一段简介代替项目档案

这次迭代没有继续加一个功能模块，而是回头完善 AI-assistant 的项目页。我把原来只有一句简介、几项泛化技术标签的卡片，补成了能说明项目当前状态的项目档案。

这个动作看起来像文案工作，实际是一次边界梳理。项目一旦同时有已完成的对话闭环、正在准备的 RAG、未来的 Agent 和评测能力，如果页面只写“一个 AI 助手项目”，读者无法判断它现在能做什么，也无法判断哪些内容只是路线图。

项目页应该回答什么

我希望项目页至少能让第一次打开的人在一分钟内得到五个答案：项目解决什么问题、服务谁、现在已经做到了哪里、下一步怎么走、哪些风险还没有解决。

因此，这次将项目页组织为以下层次：

1. 定位与目标用户：这是一个帮助 Java 后端开发者进入 AI 应用工程实践的企业级 AI 助手平台，不是泛泛的个人效率工具。
2. 当前状态与技术栈：状态明确为“V1 对话 MVP 已落地，持续迭代中”；技术栈只列当前可验证的 Vue 3、Spring Boot、FastAPI、PostgreSQL、Redis、Milvus 与 Docker Compose。
3. 核心价值与 MVP 范围：把会话、模型调用、请求上下文、调用日志、健康检查等已实现能力逐项列出。
4. 路线图：V2 的 RAG、V3/V4 的权限和 Agent、V5-V7 的评测与网关分别放入后续阶段。
5. 风险与注意事项：把尚未接正式认证、尚非端到端真实流式、外部模型调用的失败补偿、RAG 权限前置等问题写出来。

为什么不只写技术栈

“Spring Boot + FastAPI + Milvus”并不能说明项目做成了什么。技术栈是材料清单，不是交付说明。一个项目页如果只堆技术名词，会让已经实现的能力和未来设想混在一起，最终既不利于读者理解，也不利于自己复盘。

例如 Milvus 已经作为 Compose 依赖运行，但业务 collection、文档上传、分段、向量化和检索问答尚未完成。把“Milvus”写进当前技术栈是事实；把“企业知识库问答已完成”写成项目能力则不是事实。两者只差一句话，可信度却完全不同。

同样，当前后端已有 SSE 事件入口，但前端仍然使用同步对话接口，且服务端是在拿到完整答案后分段发送。项目页没有把它包装成“已经实现低延迟流式聊天”，而是把真实 token 流与断连收尾列入后续风险。对一个长期项目而言，保留这种不完整比提前报喜更有价值。

项目页和项目文章如何配合

项目页负责给出全貌，项目文章负责保存具体判断。前者适合回答“现在在哪、之后去哪”；后者适合展开“为什么这样拆 Java 和 Python”“为什么先做请求上下文”“健康检查为什么要区分存活和就绪”。

两者不应互相替代。只写文章会让读者找不到主线；只维护项目页又会丢失设计取舍和踩坑细节。当前 AI-assistant 页面下的前三篇文章，正好分别对应对话闭环、请求上下文和运行就绪检查；项目页再把它们放回同一个版本阶段中。

后续怎样维护

我给自己定下的更新规则很简单：每完成一个可演示、可验收的迭代，就更新项目页中的状态、MVP 或路线图，并补一篇项目文章；如果发现某项风险已经被解决，也要同步从风险区移到已完成能力，而不是让页面长期停留在旧状态。

这个方法不适合一次性、没有长期维护计划的小练习；但对 ai-study 这种要经历多个版本、希望沉淀成作品集的项目很合适。项目页不是发布时才写的介绍，而应该是一份随代码一起演进、可以接受读者核对的活档案。