主题
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/§15 | 30 分钟 |
| 要改代码 | 功能地图定位 → §3 模块卡 → 展开「实现细节」→ 对应测试类 | 按需 |
| 排障 / 运维 | 按问题找答案 → §5 链路 → §11 运维 → 附录 C/D/E | 按需 |
阅读约定
- 模块卡:每个模块开头固定一张表(一句话职责、用户功能、关键设计、入口、数据表),先看它就能知道这个模块管什么。
- 折叠细节:
<details>折叠块里是类名、表结构、状态机、失败边界等实现细节,默认收起,需要时点开,不影响通读。 - 参考层:§6.2 配置键表、附录 L 端点全表、附录 M 数据字典是检索用的,不必通读。
- 所有数字(Java 文件、表、端点、测试、规则数)都由架构闸与文档检查器机械核对,改代码不同步文档会直接变红。
目录
完整目录(点开;日常用上面的功能地图与章节速览即可)
- 一、项目全景
- 二、架构与工程纪律
- 三、功能模块详解
- 3.1 module_system:系统、身份与站点配置
- 3.2 module_blog:内容、互动与门户数据
- 3.3 module_note:完全私有的笔记
- 3.4 module_daily:日程、课表与提醒
- 3.5 module_memory:长期记忆、关系层与主动消息选材
- 3.6 module_llm:模型通道、出网闸与用量账
- 3.7 module_ai:分身、对话、写作、知识库与每日总结
- 3.8 module_agent:AI 助理的工具面(MCP)与人设
- 3.9 module_conversation:DSH 会话采集、回看与附件
- 3.10 module_notify:通知投递与主动性预算
- 3.11 module_ops:运维台、导入导出与 AI 看板
- 四、扩展平台
- 五、跨模块关键链路
- 六、配置
- 七、数据结构与生命周期
- 八、接口与协议
- 九、前端实现(后台 + 门户)
- 十、微信桥(
deploy/agent/wechat-bridge) - 十一、部署与运维
- 十二、质量与验证
- 十三、已知缺口与设计取舍
- 十四、文档维护约束
- 十五、待决策事项(需要博主拍板;2026-11-17 逐项实测确认)
- 附录 A:后台路由全表
- 附录 B:门户路由全表
- 附录 C:定时任务全表
- 附录 D:错误码全表
- 附录 E:部署脚本全表
- 附录 F:关键链路时序(照着读代码)
- 附录 G:后台页面清单
- 附录 H:门户页面清单
- 附录 I:后台 API 模块 → 后端端点
- 附录 J:页面 → API 模块依赖
- 附录 K:MCP 工具全表(主 30 + 扩展 40 = 70)
- 附录 L:全部端点清单
- 附录 M:数据字典
- 附录 N:能力目录(48 项)