主题
一、项目全景
1.1 这个项目是什么
一句话:一个"个人博客 + 私人生活操作系统 + 有长期记忆的 AI 伙伴"的单机全栈项目。
它同时是三个东西,共享一套数据与一套权限边界:
| 身份 | 面向谁 | 核心内容 | 写入口 |
|---|---|---|---|
| 公开博客(门户) | 任何访客 | 文章 / 说说 / 相册 / 页面 / 友链 / 留言板 / 订阅 / 站内搜索 / 数字分身试聊 | 评论、留言、订阅、分身对话(均受验证码/限流/敏感词/开关约束) |
| 私人工作台(后台) | 博主本人 | 内容管理、笔记、日程待办、AI 中心、扩展中心、运维台、安全设置 | 全部人工操作;JWT + IP 白名单 + 审计 |
| AI 伙伴(助理) | 博主本人(微信 / 后台对话) | 长期记忆、主动消息(晨报/关怀/提醒/周复盘)、写作与日报、音乐… | MCP 工具面(令牌 + scope)、微信桥、扩展平台 |
明确不是什么(避免误读):
- 不是多租户 SaaS:全库没有 tenant 概念,单实例、单博主、多访客只读;
- 不是无状态云原生应用:刻意选择 MySQL 单库 + 单实例 + 无 MQ/Redis,用 DB 轮询/唯一索引做幂等与调度;
- 不是"通用 AI Agent 平台":AI 的能力被收窄成有边界、可审计的工具面(MCP 30 个主工具 + 扩展平台 40 个工具), 写操作只允许"记下来/做草稿",发布权永远在人手里;
- 不是内容 CMS 全家桶:只有单人博客需要的那一部分(文章/页面/说说/相册/评论/友链/订阅),没有工作流、多作者、审核队列。
1.2 设计哲学(贯穿全项目的 10 条纪律)
这些不是口号,每一条都有对应的代码结构或闸门;后面的模块章节会反复引用。
| # | 纪律 | 含义 | 落到哪里 |
|---|---|---|---|
| 1 | 判据为空 ≠ 通过 | "没记录"只能说明没记录,不能推出"没做/没问题";状态必须能被证明 | 能力健康看板、sys_job_log 每轮必写、覆盖率闸门 CoverageService |
| 2 | 不静默降级、不假成功 | 要么做成,要么如实说没做成;回执写"没找到/没生效"而不是"已保存" | MCP 工具回执、R 统一响应、RuntimeResult.skip 的跳过理由 |
| 3 | 隐私分级 + 出网台账 | 内容分 public/internal/private;每一次交给模型的内容都记字节与级别,不记正文 | EgressLedger、RagService 的 publicOnly 数据层过滤、记忆隐私档 |
| 4 | AI 只写草稿,不发布 | 发布动作唯一入口是人(后台按钮);AI 只能创建草稿/建议 | article.createDraft 能力、发布事件由人触发 |
| 5 | 幂等优先 | 重复投递、重试、重启都不能产生第二条副作用 | dedup_key 唯一索引、run identity、摄取水位、提醒 planDue |
| 6 | 可降级但有兜底 | 外部依赖(AI/DSH/微信/邮件)挂了要能降级,且降级本身可见 | 模板兜底(润色失败)、通知通道降级、fail-open 但有 warn 的出网闸 |
| 7 | 人机边界显式 | 什么必须人工确认(HIGH 风险写、生产恢复、发布)写在代码与文档里 | 扩展审批 ExtensionGrantService、恢复脚本的 --allow-production --yes |
| 8 | 时间与钱的账要能对 | token 用量、成本、预算、提醒时间都有确定口径与可查账本 | ai_token_usage、proactive_log、extension_budget_ledger、ProactiveComposeCacheService |
| 9 | 迁移即代码 | 数据库结构只能通过 Flyway 前进,不手改;配置键必须由迁移登记 | 163 个迁移、SysConfigServiceImpl.saveBatch 的"键未登记"拒绝 |
| 10 | 文档是可执行事实 | 规模数字、端点、表、配置键、脚本都被闸门核对 | ArchitectureGuardTest 24 条规则 + docs/tools/check-*.mjs |
1.3 三个运行面与四个外部协作者
| 运行面 | 技术 | 谁在跑 | 入口 | 关键点 |
|---|---|---|---|---|
| 后端 | Spring Boot 3.5 / Java 17 / MySQL 8.2 / MyBatis-Plus | Docker 容器 vite-cosmos-app-prod(host 网络) | https://vite66.cn/api/** | 所有业务与调度的唯一写入口;单实例 |
| 后台 | Vue 3 + Element Plus + Vite + TS | 浏览器(/admin/) | JWT 登录 | 内容/日程/AI/扩展/运维的全部人工操作入口 |
| 门户 | Vue 3 + Vite + TypeScript(PWA) | 浏览器(/) | 公开 | 只读为主;评论/留言/订阅/分身为写入口;SEO 由后端 SeoController 出 sitemap/rss |
四个"不是本项目代码、但属于链路"的协作者:
| 协作者 | 形态 | 作用 | 与本项目的关系 |
|---|---|---|---|
| DSH(DeepSeek Harness) | 本机 Node 进程 dsh web --host 127.0.0.1 --port 3080 + headless 会话 | AI 对话的真正模型执行者;微信桥把消息交给它;它反过来通过 MCP 调用博客能力 | 通过 POST /api/agent/mcp(JSON-RPC)与桥 /compose、/agent 交互 |
| 微信桥 | Node 常驻进程(systemd cosmos-wechat-bridge) | 微信收发、流式/超时答复、主动推送出口、后台对话调度、扩展 agent 运行时 | bridge.mjs + lib/;HTTP 端点 8790 |
| Hindsight | 本机 HTTP 服务(8890,Docker) | 长期记忆的存储/检索/反思引擎(语义检索、观测、知识页) | module_memory 的 HindsightClient / MemoryFacade |
| MySQL | 容器 cosmos-mysql,127.0.0.1:3307 | 唯一事实库(100 张表) | 所有模块 + 扩展平台账本 |
生产上还挂着若干"宿主层探针":
chain-probe.sh(每 5 分钟链路探针)、health-monitor.sh(每分钟健康告警)、dsh-watchdog.sh(每 2 分钟)、collect-sessions.sh(每 5 分钟采集 DSH 会话)。它们通过心跳接口把"外部进程还活着" 变成数据库里可查询的事实(见 3.11 与 五、跨模块关键链路)。
1.4 规模(机器实测,数字被架构闸校验)
下表中的数字由
ArchitectureGuardTest.docNumericClaimsMatchSource与docs/tools/check-doc-coverage.mjs校验;改代码后不同步文档会直接红。
| 维度 | 实测 | 说明 |
|---|---|---|
| 后端 Java 文件 | 812 | vite-cosmos-server/src/main/java 下全部 .java |
| 后端测试 | 216 个测试类 / 927 条用例 | mvn -o clean test(必须 clean,否则旧 class 会造成"没编译过也显示成功") |
| Flyway 迁移脚本 | 163(V1 → V163,无缺号) | 迁移目录逐文件比对,最新 V163 |
| 数据表 | 100 张(97 个表名 @TableName) | 差异 3 张是 MyBatis-Plus 不映射的只读/复合主键表 |
@Mapper 接口 | 100 个 @Mapper 接口 | — |
| 控制器 / 端点 | 79 个控制器 / 459 条路径 / 469 个方法映射 | 去重后 468 个 (verb,path);见附录 L |
| 定时任务 | 27 个 @Scheduled 方法 | 附录 C 逐行核对「类+方法+表达式」 |
| 后台页面 | src/views/ 下 89 个 .vue,整个 src/ 共 92 个 | 附录 G |
| 配置键 | 176 | sys_config 实库;§6.2 |
| 架构规则 | 24 条架构规则 | ArchitectureGuardTest 的 @Test 数 |
| 扩展能力 | 48 项 | CapabilityCatalog;附录 N |
| MCP 工具 | 70(主 30 + 扩展 40) | 附录 K;与真机 tools/list 比对 |
1.5 仓库结构与模块地图
vite-cosmos/
├─ vite-cosmos-server/ Spring Boot 后端(812 个 Java 文件)
│ ├─ src/main/java/cn/vite66/cosmos/
│ │ ├─ common/ 通用结果/异常/配置键/端口 SPI/工具(39)
│ │ ├─ framework/ 拦截器、审计切面、异常处理、时区守卫(31)
│ │ ├─ module_system/ 系统与安全(91):认证、配置、文件、邮件、统计、导航、部件、访问日志
│ │ ├─ module_blog/ 内容(109):文章/页面/说说/相册/评论/留言/友链/订阅/系列/片段/搜索/SEO
│ │ ├─ module_note/ 笔记(29):笔记本树、笔记、标签、历史、与文章互转
│ │ ├─ module_daily/ 日程(53):待办与步骤、重复系列、课表、节假日、提醒、今日一屏
│ │ ├─ module_memory/ 记忆(135):Hindsight 门面、主动消息选材/润色缓存、关系层、生活模式
│ │ ├─ module_llm/ 模型通道(34):供应商、网关、出网闸、台账、用量、模板
│ │ ├─ module_ai/ AI 应用(57):分身、对话、写作、知识库/RAG、每日总结
│ │ ├─ module_agent/ 助理工具面(41):MCP 服务、11 个工具 provider、人设/权限、指令生成
│ │ ├─ module_conversation/ 会话(38):DSH 会话摄取、回看、附件、后台对话桥接
│ │ ├─ module_notify/ 通知(22):通道降级、重试、主动预算账本
│ │ ├─ module_ops/ 运维(24):健康/DB/清理/备份/版本/巡检/导入导出/AI 运维台
│ │ └─ platform/ 扩展平台(108):包/版本/安装/触发器/运行/能力/策略/效果/自愈
│ └─ src/main/resources/db/migration/ 163 个 Flyway 迁移(V1–V163)
├─ vite-cosmos-admin/ 后台 SPA(Vue 3 + Element Plus + Playwright e2e)
├─ vite-cosmos-web/ 门户 SPA(Vue 3 + PWA)
├─ deploy/ 部署:compose、脚本(32)、微信桥、Hindsight、监控、systemd 单元
└─ docs/ 说明书(本文)、审查记录、配置台账、工具脚本1.6 技术栈
| 层 | 选型 | 为什么 |
|---|---|---|
| 语言/框架 | Java 17 + Spring Boot 3.5(MVC、Validation、Actuator 关闭对外) | 单人可维护的成熟栈;注解式拦截器/切面足够表达横切纪律 |
| 持久层 | MyBatis-Plus + Flyway | 手写 SQL 与 Lambda Wrapper 混合;迁移可追溯、只前进 |
| 数据库 | MySQL 8.2(utf8mb4,无物理外键) | 单机事务与唯一索引足够;跨模块逻辑引用避免迁移顺序地狱 |
| AI 通道 | OpenAI 兼容协议(可配多 provider) | 抽象 AiGateway,屏蔽厂商差异;出网闸与台账统一在网关层 |
| AI 助手运行时 | DSH(headless profile + MCP 工具) | 模型/工具/会话交给成熟的 agent 运行时;博客只提供"工具与事实" |
| 记忆 | Hindsight(HTTP) | 语义检索、观测归纳、知识页;MySQL 保留结构化事件与账本 |
| 后台 | Vue 3 + TypeScript + Element Plus + md-editor-v3 | 单人开发效率;表格/表单场景成熟 |
| 门户 | Vue 3 + Vite + PWA | 静态化部署友好、首屏轻;客户端路由 + 后端 SEO 端点 |
| 微信 | @tencent-weixin/openclaw-weixin iLink 协议(MIT 插件) | 不安装 OpenClaw,只复用协议层;桥做协议适配 |
| 部署 | Docker Compose + 宿主 systemd/cron + nginx | 单机运维简单;备份/监控/探针都在宿主层 |
1.7 演进史(为什么长成现在这样)
| 阶段 | 关键变化 | 留下的设计痕迹 |
|---|---|---|
| 2026-10 | 单体博客 + 后台 + 门户;MySQL 单库 | R 统一响应、软删除、逻辑引用、审计切面 |
| 2026-10 中 | AI 助理(M46):DSH + MCP 工具面;微信桥 | MCP JSON-RPC 端点、agent 令牌 scope、instructions 端点 |
| 2026-10 末 | 记忆体系 v18:Hindsight 取代 MySQL 镜像;隐私分级/出网台账 | MemoryFacade、EgressLedger、proactive_log、预算 |
| 2026-11 初 | 扩展平台(V131):包/版本/触发器/能力/运行/策略 | 系统扩展(晨报/日报/关怀/提醒…)从 Java Job 迁到 builtin 扩展 |
| 2026-11 中 | 主动消息统一(V162/V163):扩展能力 + 预润色缓存 + 同步润色 | ProactiveComposeCacheService、capability compose.prefetch/cached |
| 2026-11-17/18 | 全项目审查 21 轮 + 收官核验:修死代码、假成功、静默失效 | 文档即事实、每轮干净测试、审查记录成为设计资产 |
| 2026-11-19 | 文档重写(本版):以模块与实现为主线的设计说明书 | 阅读路径、模块卡片、接口/数据字典移入附录 |
1.8 怎么读这份文档
| 你是 | 建议路径 |
|---|---|
| 第一次接触 | 1.1–1.4 → 二、架构与工程纪律 → 各模块的"一页速览"表格 |
| 想改某个功能 | 直接在 三、功能模块详解 找模块 → 看「数据模型 / 核心流程 / 代码索引」→ 跑该模块的测试 |
| 要加一个扩展/插件 | 四、扩展平台 → 附录 F(关键链路)→ 附录 N(能力目录) |
| 排查线上问题 | 五、跨模块关键链路 + 十一、部署与运维 + 附录 C/D/E |
| 只想看接口/字段 | 八、接口与协议 + 附录 L(全部端点)+ 附录 M(数据字典) |
| 评审设计 | 1.2 设计哲学 → 六、配置 → 十二、质量与验证 → 十五、待决策事项 |