Skip to content

ViTe 小宇宙(vite-cosmos)项目说明书 ​

版本:2026-11-19(文档重写版,结构以功能模块与实现原理为主线)

这份文档回答三个问题:它实现了什么、为什么这么设计、具体怎么实现的。

它是"设计文档 + 实现导读"的合体:每个功能先给职责边界与设计取舍,再给数据模型、 状态机、关键类与算法,最后给失败形态与代码索引。所有数字与清单都能被仓库里的 闸门(架构规则 / 文档检查器 / 配置台账)机械核对 —— 文档写错会红,不靠自觉。

维护纪律见 十四、文档维护约束;最近一次全链路审查记录见 docs/全项目审查记录.md。

五分钟看懂这个项目 ​

它是什么:一个单机部署的"个人博客 + 私人生活操作系统 + 有长期记忆的 AI 伙伴"。 一套后端(Spring Boot)+ 两个前端(门户 / 后台)+ 四个协作者(DSH、微信桥、Hindsight、MySQL)。

一眼架构 ​

用户浏览器 ──> 门户(公开只读 + 评论/订阅)   后台(JWT,全部人工操作)
                        │                            │
                        └────────────┬───────────────┘
                                     ▼
                        后端 Spring Boot(单实例,唯一写入口)
                        ├─ 11 个业务模块(内容/笔记/日程/记忆/AI/…)
                        ├─ 扩展平台(触发器 + 能力 + 效果 + 审批)
                        └─ MySQL(100 张表,唯一事实库)
                                     ▲
        微信/邮件 <── 微信桥(Node)<── DSH(AI 运行时)──> MCP 工具面(30 + 40)
                                     │
                              Hindsight(长期记忆,HTTP 8890)

功能地图(按"用户能做什么"索引) ​

功能域用户看到什么关键设计(一句话)深读
博客内容写文章(草稿/定时/历史/系列)、页面、说说、相册文章状态机 + 发布事件;门户 SQL 层强制可见性§3.2
互动与订阅评论、留言、友链、订阅邮件、站内搜索访客写四层防护;发布事件 AFTER_COMMIT 发订阅§3.2
笔记私有笔记本树、标签、历史、回收站、转文章草稿完全私有:不进门户 / RAG / 访客分身§3.3
日程与提醒今日一屏、待办(步骤/重复)、按天课表、节假日、到点提醒课次按天存 + 幂等提醒 + 时间锚点绝不提前§3.4
记忆与关系助手记得事实/偏好/情绪;线头、关怀、分歧、仪式;生活统计Hindsight 语义权威 + MySQL 结构化/关系状态 + 出网台账§3.5
AI 助手微信对话、后台对话、数字分身、写作、知识库DSH 当大脑,博客只提供有边界的 MCP 工具与事实§3.7 / §3.8
主动消息晨报、晚报、关怀、周复盘、提醒扩展触发器 + 选材 + 润色兜底 + 通知通道降级§5.1
每日总结每天一篇私密日记(可选生成文章草稿)时间点轮询 + 行级 claim + 状态机;发布权在人§3.7
扩展平台开发/安装/运行插件,给助手加新能力草稿→校验→dry-run→签名→能力网关→审批→自愈§四
通知微信 / 邮件 / 站内;失败自动重试幂等抢占 + 降级链 + "通道自报成功"才算 sent§3.10
系统与运维登录安全、配置中心、文件、审计、备份恢复、健康体检JWT + IP 白名单 + 加密配置 + 守卫/体检脚本§3.1 / §十一
前端与数据门户 PWA、后台 SPA;100 表 / 468 端点 / 70 工具Vue 3 双端;Flyway 只前进;文档被闸门机械校验§九 / §七 / §八

按问题找答案 ​

我想…先看再看
5 分钟知道项目能做什么上面的「功能地图」§1 项目全景
改某个功能§3 对应模块的「模块卡」点开该模块的「实现细节」+ 跑模块测试
排查线上问题§5 关键链路§11 运维 + 附录 C/D
加接口/表/配置键§2.9 变更纪律§8 接口 / §7 数据 / §6 配置
开发或安装扩展§四 扩展平台附录 N 能力目录
查某个 API / 表 / 配置键附录 L / 附录 M / §6.2—
理解"为什么这么设计"§1.2 设计哲学§2 架构纪律 + 各模块「关键设计」

三种阅读路径 ​

你是读什么大约
第一次接触 / 评审本页 → §1.2 设计哲学 → §2 架构纪律 → §12 质量 → §13/§1530 分钟
要改代码功能地图定位 → §3 模块卡 → 展开「实现细节」→ 对应测试类按需
排障 / 运维按问题找答案 → §5 链路 → §11 运维 → 附录 C/D/E按需

阅读约定 ​

  • 模块卡:每个模块开头固定一张表(一句话职责、用户功能、关键设计、入口、数据表),先看它就能知道这个模块管什么。
  • 折叠细节:<details> 折叠块里是类名、表结构、状态机、失败边界等实现细节,默认收起,需要时点开,不影响通读。
  • 参考层:§6.2 配置键表、附录 L 端点全表、附录 M 数据字典是检索用的,不必通读。
  • 所有数字(Java 文件、表、端点、测试、规则数)都由架构闸与文档检查器机械核对,改代码不同步文档会直接变红。

目录 ​

完整目录(点开;日常用上面的功能地图与章节速览即可)
---

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。