Skip to content

三、功能模块详解 ​

本章速览:11 个模块按"用户能看到的功能"组织。每个模块先给一张模块卡(一句话职责 / 用户功能 / 关键设计 / 入口 / 数据表),点开折叠块才看类、状态机与失败边界。建议先读模块卡定位,再按需展开。

模块速查:11 个模块一句话定位(点开)
模块一句话职责主要数据表你能用它做什么小节
module_system身份、配置与站点底座sys_*(13)登录、改站点配置、传图、发订阅邮件、看审计§3.1
module_blog内容生产与门户数据面blog_*(14)写文章、发说说、管相册、评论留言、搜索§3.2
module_note完全私有的笔记note_*(5)记笔记、回收站、转文章草稿§3.3
module_daily日程、课表与提醒daily_*(5)待办/步骤/重复、按天课表、到点提醒§3.4
module_memory长期记忆、关系层与选材ai_* 记忆/关系表(10+)助手记住与回忆、线头/关怀/分歧、生活统计§3.5
module_llm模型通道与出网总闸ai_provider 等(4)配模型、看向量与成本、额度/熔断§3.6
module_aiAI 产品层ai_conversation 等(5+)对话、分身、写作、知识库、每日日记§3.7
module_agentMCP 工具面与人设agent_token 等(2)让微信/DSH 查日程、写记忆、记事件§3.8
module_conversation会话采集与附件agent_*、chat_attachment(7)回看历史对话、管聊天附件§3.9
module_notify通知唯一出口notify_*、proactive_log(3)晨报/提醒送达、失败重试§3.10
module_ops运维台与导入导出跨模块只读健康检查、清理、导入导出、能力看板§3.11

3.1 module_system:系统、身份与站点配置 ​

模块卡 ​

项内容
一句话身份、配置与站点基础能力的底座:登录/安全、配置开关、文件、邮件、导航/部件、订阅、心跳与审计。
用户功能后台登录与安全中心;站点名称/页脚/开关等配置;图片与附件上传;邮件测试与订阅发信;导航/底部 Tab/部件;访问/搜索/登录审计;健康检查与外部心跳。
关键设计① 配置写侧校验:脏值/非法枚举/错误时间格式当场拒绝,不靠消费方兜底;② 敏感值 enc: 加密入库、接口只回掩码;③ 三套鉴权主体分离,后台 IP 白名单先于 JWT 执行。
职责认证与安全、站点配置、文件上传、邮件、导航/部件、访问与搜索日志、订阅、心跳
入口/api/admin/system(后台)、/api/portal/site(门户公开配置)、/api/health*
数据表sys_user、sys_config、sys_file、sys_file_folder、sys_audit_log、sys_login_log、sys_job_log、sys_mail_log、sys_search_log、sys_subscriber、sys_visit_log、sys_widget、sys_api_key
实现细节(点开:类、状态机、表结构、失败边界)
项内容
关键类AuthServiceImpl、SecurityServiceImpl、SysConfigServiceImpl、FileServiceImpl、MailServiceImpl、HeartbeatServiceImpl、StatsServiceImpl、AuthInterceptor、AuditAspect
失败形态登录失败锁定;SMTP 未配置静默跳过(不影响主流程);配置脏值写侧拒绝(§6.2)

认证与安全 ​

登录:POST /api/admin/auth/login 收用户名/密码;AuthServiceImpl 用 bcrypt 校验, 失败次数超阈值锁定(sys_login_log 记录 IP/UA/结果),成功后签 JWT(HMAC,COSMOS_JWT_SECRET)。 AuthInterceptor 只校验 /api/admin(除登录/验证码等白名单);前端把 token 放 Authorization: Bearer,过期统一 401 → 前端跳登录。

后台 IP 白名单(SecurityServiceImpl + AdminIpGuardInterceptor):白名单存在 site.security.* 配置里;拦截器先于 JWT执行,登录接口也受约束。匹配支持精确 IP 与 CIDR。 这是"网络层兜底":即使密码泄漏,非白名单 IP 也进不来。

API Key:sys_api_key 存哈希与前缀,供脚本/程序调用;check-agent-token.sh 做只读自检。

登录告警:异地/新 UA 登录写站内通知并发邮件(SecurityServiceImpl 告警链), 告警去重避免轰炸。

站点配置(全项目最关键的"开关面") ​

SysConfigServiceImpl:

  • 存储:sys_config(key, value, remark, secret);敏感项值以 enc: 前缀密文入库 (CryptoUtil + COSMOS_SECRET_KEY),接口列表只回 ******。
  • 读取:getValue(key, default) 带单键 30 秒缓存;保存路径在事务提交后清缓存 (TxHooks.afterCommit),所以后台改完立即生效,直接改库最多 30 秒收敛。
  • 写入:saveBatch(items) 做四件事 —— ① 键名格式校验(^[a-z][a-z0-9.-]{1,95}$);② 只允许更新迁移里已种下的键 (防止运行期凭空造键/重建已删旧键);③ 结构化取值校验(时间键必须 HH:mm、 出网档位枚举、熔断模式枚举、额度键非负整数 —— 见 6.2);④ 提交后发布 ConfigSavedEvent,让关心特定键的组件(如日报时间 → 扩展触发器 cron)同步。
  • 敏感项留空 = 不修改(前端回显掩码,用户没动就不覆盖)。

为什么把校验放在写侧:消费方普遍采用"读不出来回落默认"以保证不因脏值停摆, 于是错值表现为"保存成功、行为未变/悄悄改变"。写侧拒绝没有停摆风险,还能当场说明格式。

文件与媒体 ​

FileServiceImpl:上传 → 校验扩展名与 MIME 白名单 → 随机文件名 + 日期分目录 → 写 sys_file(url/大小/sha256/文件夹)→ 通过 FileStoragePort 落盘(生产为挂载卷 /opt/vite-cosmos/uploads)。删除时先查引用:MediaReferenceProvider 由各模块实现 (文章正文/封面、说说、相册、笔记图标、友链头像、站点配置…),引用反查不到就保守保留, 避免"清理孤儿文件"误删仅被某个新引用面引用的图(审查 #68 修的就是引用面漏项)。

上传安全:X-Content-Type-Options: nosniff、私有附件独立目录、下载时按服务端校验过的 扩展名推导 MIME(不信任客户端声明的类型)。

邮件、订阅与通知前置 ​

MailServiceImpl:SMTP 参数全部来自 sys_config(授权码密文),未配置时静默跳过并只记 sys_mail_log(失败不影响主流程);sendToAdmin / sendToSubscriber 两个语义分开, 订阅退订链接带签名 token(site.subscribe.*)。

SubscriberServiceImpl:门户订阅 = 邮箱 + 验证码 + 限流;退订走带签名的链接; 新文章发布时 SubscriberNotifyListener 监听 ArticlePublishedEvent(AFTER_COMMIT), 按订阅列表批量发信,失败写日志但不阻塞发布。

导航、部件与门户配置 ​

  • 导航:site.nav.items 存 JSON(导航项 + 移动端底部 Tab),NavService 读/写/重置默认; 门户通过 /api/portal/site 拿装配结果。
  • 部件(Widget):区域 + 部件模型;WidgetService.portalLayout() 只返回 enabled=1 的部件, 按区域分组,并附带布局配置(侧栏位置、目录形态、注入代码、页脚版权开关)。
  • 站点信息:SiteController 一次返回站点名/描述/页脚/备案/社交链接/开关等, 门户首屏只发一个请求。

心跳:让"外部进程活着"可查询 ​

HeartbeatServiceImpl 把 bridge / chain-probe / ingest 的上报写进 sys_job_log (每个来源一行、update_time 即最后上报),HeartbeatWatchJob 每 5 分钟检查超时并恢复/告警。 好处:能力健康看板与 doctor.sh 不需要各自造轮子,"桥还活着吗"直接查库。

失败与边界 ​

  • JWT 过期/签名错 → 401;IP 不在白名单 → 403;账号锁定按失败次数与时间窗;
  • SMTP 未配置/发送失败:主流程继续,日志留痕(订阅/告警可能因此静默——doctor.sh 会提示);
  • 配置缓存 30 秒内可能读到旧值(保存会主动失效,手改库最多 30 秒);
  • 心跳写入失败只告警不重试(外部进程下一轮会再报)。

3.2 module_blog:内容、互动与门户数据 ​

模块卡 ​

项内容
一句话内容生产与门户数据面:文章、页面、说说、相册、评论/留言/友链、搜索与 SEO。
用户功能写文章(草稿/定时/历史版本/系列/片段)、自定义页面、说说时间线、相册、评论与留言(含楼中楼与审核)、友链申请、分类/标签/归档、站内搜索、sitemap/rss。
关键设计① 文章状态机 + AFTER_COMMIT 发布事件驱动订阅与 AI 增强;② 门户接口在 SQL 层强制 status=1/可见性;③ 访客写统一四层防护:验证码→限流→敏感词→审核。
职责文章/页面/说说/相册/评论/留言/友链/分类/标签/系列/片段/搜索/SEO/订阅联动
入口/api/admin/blog(95 端点)、/api/portal/blog(只读 + 评论/留言/订阅)
数据表blog_article、blog_article_history、blog_article_tag、blog_page、blog_talk、blog_album、blog_photo、blog_comment、blog_message、blog_friend_link、blog_category、blog_tag、blog_series、blog_snippet
实现细节(点开:类、状态机、表结构、失败边界)
项内容
关键类ArticleServiceImpl、ArticlePublishJob、ArticleEventListener、CommentServiceImpl、SearchServiceImpl、SeoController、MarkdownRenderer
失败形态门户强制 status=1;评论四层防护;发布事件 AFTER_COMMIT;导入内容转义

文章:一条内容的完整生命周期 ​

状态机:

草稿(status=0) ──发布──> 已发布(status=1) ──下架──> 草稿
   │                     │
   │ 定时发布(pubDate)     ├─ 修改 → 历史快照(blog_article_history)
   └── 删除(软删)          └─ 删除 → 回收站/软删(可恢复)
  • 保存:ArticleServiceImpl.save 统一入口;标题去空白、摘要缺省由正文截取、 Markdown 原文入 contentMd、渲染 HTML 入 content(MarkdownRenderer 白名单清洗); 标签走 blog_article_tag 关系表(先删后插)。
  • 定时发布:ArticlePublishJob 每分钟扫描 status=0 AND pub_date <= now 的文章并发布; 发布动作发 ArticlePublishedEvent(事务提交后)。
  • 历史版本:每次保存前把旧内容写 blog_article_history;后台可看 diff。
  • 事件消费者:
    • SubscriberNotifyListener → 订阅邮件;
    • ArticlePublishAiListener → 自动摘要/标签/向量化(异步,失败不阻塞发布);
    • ActionRetainService(记忆模块)→ 把"发布"作为可统计事件。
  • 门户可见性:所有 portal 服务在 SQL 层强制 status=1,文章详情额外按 visibility 与密码保护字段过滤;草稿/下架不可能从门户泄漏。

页面、说说与相册 ​

类型实现要点
自定义页面 blog_pageslug 唯一;Markdown 正文;导航可挂;门户 /page/:slug
说说 blog_talk短文本 + 图片/表情;时间线倒序;门户首页/说说页分页
相册 blog_album + blog_photo两级结构;照片含描述/排序/EXIF 可选;门户瀑布流;封面可用第一张
系列 blog_series有明确阅读顺序(sort);文章详情返回"所属系列 + 上一篇/下一篇";删除系列只解除归属不删文章
片段 blog_snippet可复用 Markdown 块,编辑器一键插入(署名/免责声明/常用命令)

分类、标签与搜索 ​

  • 分类:单层树(parent_id 预留),slug 唯一;删除前要求无文章或迁移。
  • 标签:多对多;标签云按文章数排序。
  • 搜索 SearchServiceImpl:覆盖文章 + 页面 + 说说三类公开内容;标题/正文/摘要多字段 LIKE + 相关度排序;门户 /search 与 MCP 搜索工具共用(MCP 侧走 SearchService 而非裸 SQL)。

SEO 与门户元数据 ​

SeoController 输出 /sitemap.xml(只含已发布文章/页面/分类/标签/说说/相册)、/rss.xml (最近文章)、robots.txt;站点域名与是否启用由配置决定。MetaPortalController 提供 分类/标签/归档的聚合数据(归档按年月分组)。门户是 SPA,首屏 SEO 依赖这些服务端端点。

评论、留言与友链:同一条"访客写入防线" ​

访客写入口(评论/留言/友链申请)统一四层:

  1. 验证码(CaptchaService,图片验证码,内存 TTL 存储,一次性消费);
  2. IP 频率限制(内存滑动窗口,防刷屏);
  3. 敏感词(site.comment.forbidden_words 逗号分隔,命中直接拒绝并提示);
  4. 审核开关(site.comment.audit.*):需审核的进 pending,博主批准后可见。

评论支持楼中楼(parentId)、博主回复、点赞、状态(显示/隐藏/待审)、举报(管理端处理); 留言板同理但无楼中楼。所有通过的内容都由 MarkdownRenderer 做 HTML 清洗, 防存储型 XSS。

失败与边界 ​

  • 文章不存在/未发布 → 门户 404 语义(code=20001 或 10004,按接口约定);
  • 定时发布与手动发布并发:发布动作幂等(状态判断),事件只发一次(同一事务内状态变更);
  • 评论审核关闭时直接可见,但敏感词与限流仍生效;
  • 订阅邮件失败不回滚发布;
  • 导入外部内容(见 3.11)默认草稿且 HTML 转义,绝不直接发布。

3.3 module_note:完全私有的笔记 ​

模块卡 ​

项内容
一句话完全私有的笔记工作区,与公开博客严格隔离。
用户功能笔记本树、Markdown 笔记、标签/星标、历史版本、回收站恢复、把笔记转成文章草稿。
关键设计① 只有 admin 端点可达,不进门户/RAG/访客分身;② 删除保留标签关系,恢复不丢标签;③ 笔记转文章只创建草稿,发布由人决定。
职责笔记本树、笔记 CRUD、标签、星标、历史、回收站、笔记↔文章互转
入口/api/admin/note(20 端点,全部 admin-only)
数据表note_notebook、note_note、note_note_tag、note_tag、note_history
实现细节(点开:类、状态机、表结构、失败边界)
项内容
关键类NoteServiceImpl、NotebookServiceImpl、NoteArticleSyncListener
失败形态删除保留标签关系(回收站恢复不丢标签,审查 #55);私有内容不进门户/访客

结构与实现 ​

  • 笔记本树:note_notebook(parent_id, sort);移动节点时校验不能移入自己的子树; 删除笔记本要求其下无笔记(或指定迁移目标)。
  • 笔记:Markdown 正文 + 摘要;starred 星标;notebook_id 归属;标签多对多。
  • 历史:note_history 保存每次修改前快照;可回滚(写回并再记一条历史)。
  • 回收站:软删 deleted=1;trash/page 列出、restore 恢复;恢复时保留原有标签关系 (早期实现删除时清了关系,导致恢复丢标签 —— 审查 #55 修复)。
  • 全文检索:后台列表的 keyword 查询走标题/正文 LIKE;不引入 ES(数据量在单用户量级)。
  • 笔记↔文章:NoteArticleSyncListener 在笔记被转为文章(或文章存为笔记)时维护双向引用; 转文章时只创建草稿,是否发布由人决定(设计哲学第 4 条)。

隐私边界 ​

笔记是"完全私有"数据:只有 admin 端点可达,不参与门户检索、不进 RAG 访客版、 不进访客分身上下文;记忆抽取默认也不把笔记正文当素材(见 3.5 的隐私口径)。

3.4 module_daily:日程、课表与提醒 ​

模块卡 ​

项内容
一句话日程、课表、节假日与提醒的单一事实来源。
用户功能今日一屏、待办(多步/重复系列)、按天课表、节假日三值判定、到点提醒与补投、门户「今日」。
关键设计① 课次按天存储,natural_key 唯一索引保证幂等与冲突可判;② 提醒用 dedup_key 幂等,失败可重试、超窗标 skipped;③ 时间锚点类提醒绝不提前,润色失败发模板。
职责待办(含多步与重复系列)、课表(按天)、节假日、提醒投递、今日一屏、门户"今日"
入口/api/admin/daily(35 端点)、/api/portal/daily、MCP daily_brief / daily_todo / daily_course 工具
数据表daily_todo、daily_todo_series、daily_course_session、daily_holiday、daily_reminder
实现细节(点开:类、状态机、表结构、失败边界)
项内容
关键类DailyTodoServiceImpl、DailyTodoSeriesJob、DailyCourseSessionServiceImpl、HolidayServiceImpl、DailyReminderJob/ServiceImpl、DailyOverviewServiceImpl
失败形态课程冲突 409;提醒按模式去重;节假日三值判定;越权/越期告警

待办:一条待办可以有步骤,也可以重复 ​

数据模型:daily_todo 自引用 —— parent_id 为空是任务,非空是步骤。好处是 "今日一屏"只需查一张表,步骤与任务共享状态机与排序。

状态机:

pending ──done──> done
   │  └──drop──> dropped(可 restore 回 pending)
   └─ skip(系列本次跳过,不改状态,仅不提醒)
  • 多步任务:步骤按 sort 排序;完成全部步骤不会自动完成任务(由人决定); 删除任务级联删步骤;步骤的 done 单独记录时间。
  • 重复系列:daily_todo_series 存规则(repeatRule: daily|weekdays|weekends|weekly:1,3,5)
    • 起始/结束日期;DailyTodoSeriesJob 每天 00:05 物化当天的实例(幂等:同 series+日期唯一); MCP/后台的 series_stop/resume/skip/update 管理系列。非法 repeatRule 在工具层明确拒绝 并给出可选值(不静默存一条"看起来会重复"的假规则)。
  • 提醒联动:保存/修改/删除待办时重算提醒计划(daily_reminder),删除任务时取消未投递提醒。

课表:为什么改成"按天" ​

旧模型是"星期几 + 周次"的周模板,表达不了同一时段不同周次换课、节假日调课(真实课表就是)。 M165 起改为 daily_course_session:每行 = 某天的某一节课(日期 + 课程名 + 开始/结束时间 + 地点)。 natural_key 唯一约束保证"同日期+同课程名+同开始时间"幂等,重复 add 不会造出两条。

  • 校验:end_time > start_time(否则显式拒绝,交给调用方留空按 +2h 估算 —— 审查 #78);
  • 冲突:同一时段重叠返回 409(前端可弹"调整时间");
  • 补课/调课:直接增删改当天行;PATCH 支持拖拽改期改时并重算提醒。

节假日:三值判定,而不是布尔 ​

HolidayService 返回 workday | holiday | unknown 三值。为什么不是 boolean:节假日数据源 可能没覆盖某一年,unknown 必须与"确定是工作日"区分开,否则"今天上不上课"会被猜成确定答案。 数据来自公开源(当年 + 次年),HolidayFetchJob 按 site.daily.holiday.years-ahead(0–3) 拉取并缓存 daily_holiday;含调休(workday 覆盖周末)。晨报/提醒/判定都走这一接口。

提醒:DB 轮询 + 幂等 + 双通道 ​

DailyReminderService 是"提醒点"的唯一真相:

  1. 计划:planDue(now, catchUp) 扫描课程/待办/自定义提醒,生成 daily_reminder 行, dedup_key = 类型:对象:时间 唯一索引幂等;重复扫描不会产生两条。
  2. 投递:统一模式(COSMOS_PROACTIVE_UNIFIED_ENABLED=true)下由扩展 system.reminder 每分钟触发,能力 reminder.pending.read 取出到点提醒,走"润色缓存 → 通知投递"; 旧路径 deliverDue 保留为降级/迁移期能力。
  3. 状态:pending → sent / failed / skipped;失败可 retry(后台/MCP); 补投窗口由 catchUpMinutes 控制(重启后不丢当天提醒)。
  4. 准点策略:到点前 10 分钟预润色(见 5.1),到点只读缓存;润色失败/缓存过期发模板, 绝不因为润色而晚发。发送判据:时间锚点类(课程/自定义)绝不提前,待办类最多提前 30 秒 (=调度器粒度)—— 审查 #69 的结论。

今日一屏与门户"今日" ​

DailyOverviewServiceImpl 聚合同一天的课程 + 待办(含逾期)+ 提醒计划 + 统计; PortalDailyServiceImpl 是它的隐私收窄版:门户只返回计数与课程名,不返回待办标题 (待办可能含私密信息)。两个服务共用底层查询,但输出字段不同 —— 这是"同一数据、不同可见性" 的典型实现。

失败与边界 ​

  • 课程冲突 409;非法时间显式拒绝;节假日数据缺失时 unknown 而非猜;
  • 提醒重复扫描幂等;发送失败进入 retry,超次数记 failed;
  • 重复系列物化失败会被下一次扫描补齐(幂等);
  • 待办/提醒的时区固定 Asia/Shanghai(业务时间,不走扩展平台的 UTC 口径)。

3.5 module_memory:长期记忆、关系层与主动消息选材 ​

这是全项目最复杂的模块(135 个文件、71 个端点),先给一张"层次图"再拆开讲。

调用方(MCP 工具 / 扩展 capability / 定时任务 / 后台)
        │
        ▼
MemoryFacade(统一门面:策略在这层,不在 Backend)
        │        ├─> HindsightMemoryBackend ─> HindsightClient(HTTP 8890)
        │        └─> 结构化事件/账本:ai_mem_event、ai_hs_operation、ai_egress_log…
        ▼
MySQL(结构化事实/关系状态/主动账本) + Hindsight(语义记忆/观测/知识页)

一条设计原则:语义记忆的权威在 Hindsight,结构化事件与关系状态的权威在 MySQL。 v18 之后不再维护 MySQL 的"记忆镜像表",避免两套写入互相漂移;ai_mem_event 只存 可聚合的生活事件(跑步/睡眠/消费/课程…),通过镜像 Job 生成 Hindsight 摘要。

模块卡 ​

项内容
一句话长期记忆、关系层与主动消息的选材中心(全项目最复杂的模块)。
用户功能助手记得事实/偏好/情绪/关系;语义召回与遗忘;未了线头/关怀/分歧/仪式/程序/叙事;生活事件聚合、模式与计划偏差;给主动消息选材。
关键设计① 语义记忆权威在 Hindsight,结构化事件与关系状态在 MySQL,不维护双写镜像;② 隐私三级 + 每次出网记台账(不记正文);③ 主动产出「跳过必须有理由」(开关/预算/静默/无候选)。
职责记忆写入/检索/遗忘、结构化事件、关系层(线头/关怀/分歧/仪式/流程/叙事)、生活模式与偏差、主动性选材、预润色缓存、Hindsight 运维
入口MCP 工具(memory_* / open_loop / emotion_note / care_reply / disagreement / procedure / ritual / narrative / profile_update / memory_verify / recall…)、扩展 capability、后台 /api/admin/hindsight 与 /api/admin/life
数据表ai_mem_event、ai_mem_coverage、ai_mem_metric_schema、ai_open_loop、ai_care_checkin、ai_disagreement、ai_ritual、ai_memory_procedure、ai_narrative_chapter、proactive_compose(+ Hindsight 侧库、ai_hs_* 账本)
实现细节(点开:类、状态机、表结构、失败边界)
项内容
关键类MemoryFacade、HindsightMemoryBackend、MemoryWriteServiceImpl、MemorySearchServiceImpl、MemoryForgetServiceImpl、OpenLoopServiceImpl、CareCheckInServiceImpl、DisagreementServiceImpl、RitualServiceImpl、ProcedureServiceImpl、NarrativeServiceImpl、CoverageServiceImpl、EventPatternServiceImpl、PlanDeviationServiceImpl、ProactiveComposeCacheService

记忆写入:一条"记住"要过几道关 ​

调用方(模型/扩展/后台)→ MemoryWriteCmd:

字段作用
text自洽的一句话(写入前校验非空)
typefact/preference/goal/event/emotion/relation/pattern/drift;事件类还进结构化事件管道
subject/predicate/object结构化三元组(memory_fact_upsert 用;同主语+谓语旧事实被标记"已取代"而非删除)
importance0–100;影响后续召回排序与分析素材门槛
privacypublic/internal/private;private 不进模型上下文
dedupe_key幂等键;同内容重复写不会产生第二条(服务端也会按内容算键)
provenance来源:conversation/article/manual/digest;是否 verbatim 原话
occurred_at事件发生时间(不是写入时间)—— 影响"什么时候发生的"类召回
confidence低置信进"待确认队列",人工确认后才参与检索

写入路径(MemoryWriteServiceImpl → MemoryFacade.write):

  1. 参数/隐私/去重键归一;
  2. 写 Hindsight(document_id/operation_id 幂等;异步 operation 由 HindsightOperationJob 确认);
  3. 落库校验:读回确认写入成功,失败如实返回错误(不假称"记下了");
  4. 返回 created / dedupe-hit / pendingReview 三态,MCP 回执按三态给不同话术。

记忆检索:召回不是"搜一下" ​

MemorySearchServiceImpl:

  1. 构造检索请求:语义 query + 过滤(type/privacy/state/valid_until/时间窗);
  2. Hindsight recall(读请求重试 2 次,仅对 5xx/限流/网络错误;Retry-After 尊重);
  3. 词面重排(LexicalReranker.overlap):语义分数高但字面不相关时降权;
  4. 置信校准(contractScore):语义 0.5–0.6 的"话题相近"结果对外给 0,避免假相关;
  5. 出网台账:把"交付给模型的内容"记入 ai_egress_log(级别条数/字节,不记正文);
  6. 返回 why(为什么命中)与 sourceRef(可回溯来源),让模型能引用而不是编造。

valid_until 过期的观测在检索时被过滤;privacy=private 的内容不进入上下文。

遗忘:三种粒度,必须有回执 ​

MemoryForgetServiceImpl 支持按 id / 关键词 / 会话整段遗忘;mode=soft(失效可回溯) 或 hard(物理删除,连向量一起抹)。遗忘是幂等的:已经不在了也返回成功("之前就删过")。 删除后触发向量清理(MemoryVectorPort);孤儿向量由 OrphanVectorSweepJob 每周兜底清扫。

结构化事件与生活管道 ​

ai_mem_event 记录有数值的生活事件(跑步距离/睡眠时长/消费/课程/照片…), LifeEventService 提供写入与聚合查询(次数/合计/平均/按天趋势/按地点), 供 MCP 的 event_record/event_query 使用。聚合在 SQL 层完成,不让模型自己加数字 (那是幻觉的主要来源)。

生活质量层:

能力服务实现要点
覆盖率闸门CoverageServiceImpl"任何'他没做 X'的结论,先证明'他若做了我们会知道'";输出覆盖率而不是缺席断言
生活模式EventPatternServiceImpl统计窗口内某类事件的频率变化,产出"最近不跑步了"这种可问的候选,不直接下结论
计划偏差PlanDeviationServiceImpl课表/计划 vs 实际记录,措辞是"没有记录到"而不是"你缺课了";重复≥3 次才算模式
证伪探针FalsificationServiceImpl周期性挑一条高重要度记忆去问"还是这样吗",用回答修正/证伪

关系层:让"记得"变成"相处" ​

这一组服务共同维护关系连续性,每个都有自己的状态机:

服务 / 表状态机关键设计
未了线头 ai_open_loopopen → closed / dropped;raise 记提及次数与预算读不产生副作用:listOpen 只读,提及由调用方显式 raise;预算防止"每份晨报都提同一条"
主动关怀 ai_care_checkinsent → replied / ignored;去重键 + 静默时段只负责"记录与回溯";选材/预算/静默在扩展 handler(4.5),职责分离
分歧 ai_disagreementopen → conceded/held/settled/dropped;push_count 提两次自动收口反谄媚:防"随风倒";markPushed 由 MCP disagreement(list) 触发(审查 #75)
仪式 ai_ritualproposed → active → paused/retired;done 记完成proposed 永不执行(未经同意不主动);到期判定由代码算(dueNow),不交给模型
程序记忆 ai_memory_procedurecandidate → confirmed(观察到第 2 次才升)"一次是偶然,两次才是习惯";use_count 记录使用
叙事章节 ai_narrative_chapterbuild → get;密度/覆盖天数提取式(主题频次+事件重要度+情绪弧),density=thin 时不能当完整经历讲
关系档案(PersonaSnapshot,存 Hindsight directive;旧 MySQL 表 ai_profile 已删)阶段/直言度只由本人定助手工具只能建议,不能改(红线写进工具注释)

预润色缓存:为什么只有提醒用它 ​

ProactiveComposeCacheService:到点前 lead 分钟(3–30,默认 10)把提醒文案交给 DSH 润色, 写入 proactive_compose(status=ready/failed,带模板+事实哈希、过期时间);到点只读。 失败行短 TTL(3 分钟)避免 DSH 故障时每分钟重试拖垮提醒任务;成功行额外留 40 分钟覆盖补投窗口。 其它主动消息(晨报/晚报/关怀/周复盘)到点同步润色,多等几秒没有代价,模板兜底保证不丢。

Hindsight 运维面 ​

组件作用
HindsightIngestJob/ServiceMySQL 结构化数据 → Hindsight 增量摄取(水位 ai_hs_ingest_cursor)
HindsightOperationJob轮询异步 operation,补"入队后无人确认"闭环(ai_hs_operation)
EventHindsightMirrorJob结构化事件 → 语义摘要镜像(MySQL 仍是权威)
BackfillEventJob历史回填(只补缺失,不重试失败)
HindsightConsoleController/Service后台总览、观测列表、操作详情、审计统计、知识页
HindsightUpgradeController/Service版本升级/回滚(宿主脚本,审批 + 备份)
HindsightHealthService健康探测(readiness、隔离/边界检查)
ai_hs_usage / ai_memory_archive用量与归档(只读/复合主键,不走 MyBatis-Plus)

失败与边界 ​

  • Hindsight 不可用:检索返回明确错误/降级(不编造);写入失败如实回报,不假称记住;
  • 异步 operation 未确认:Job 轮询补确认,超时标 failed 并可见;
  • 记忆写入与事件写入分属两条管道:事件聚合查询不依赖 Hindsight;
  • 主动消息"跳过"必须给理由(开关/预算/静默/无候选),空产出不允许静默(BuiltinOutputs.skip)。

3.6 module_llm:模型通道、出网闸与用量账 ​

模块卡 ​

项内容
一句话模型通道与所有 AI 出网的统一入口。
用户功能多 provider 配置与连通性测试;chat/流式/向量化/生图;用量与成本报表;每日额度与熔断;提示词模板。
关键设计① 所有出网走 AiGateway(出网闸 + 台账 + 用量);② 生图按固定 token 当量记账,不漏出限额;③ 熔断额度只统计门户侧,内部任务不挤占访客额度。
职责多 provider 配置、统一网关(chat/stream/embed/image)、出网闸与台账、用量与熔断、提示词模板、知识库向量块
入口/api/admin/ai/provider(5 端点);其余为内部 SPI:AiGateway、EgressGatePort、AiUsageGuard
数据表ai_provider、ai_prompt_template、ai_token_usage、ai_kb_chunk(+ ai_egress_log)
实现细节(点开:类、状态机、表结构、失败边界)
项内容
关键类AiGatewayImpl、OpenAiCompatibleClient、EgressGate、EgressLedger、AiUsageGuardImpl、AiProviderServiceImpl、TokenUsageStatsServiceImpl、QueryVectorCache
失败形态出网被拒/供应商错误/超时;台账写失败不影响业务;熔断只拦门户侧

Provider 配置 ​

ai_provider 一行一个通道:名称、类型(openai 兼容)、baseUrl、model、apiKey(enc: 密文)、 启用状态、超时/并发/成本单价。后台可测试连通性(发一条最小请求)、同类通道互斥激活。 AiGatewayImpl 按"启用 + 优先级"选通道,失败时按配置尝试备用通道。

网关:所有 AI 出网的唯一入口 ​

四条路径:chat(同步)、chatStream(SSE)、embed(向量化)、image(生图)。

每条路径都做四件事:

  1. 出网闸(EgressGate.check*):frozen 一律拒绝;minimal 只拦主动性/离线场景;
  2. 隐私台账(EgressLedger):记录交给外部的内容条数/级别/字节,不记正文; 生图按固定 token 当量(4000)记账,防止"生图不限额"的漏洞;
  3. 调用与重试:HTTP 超时、5xx 重试有限次数(幂等读安全,写靠 request id);
  4. 用量(ai_token_usage):场景、模型、prompt/completion tokens、成本、耗时、是否流式; 写失败只 warn,不影响回答。

QueryVectorCache:查询向量缓存 60 秒 / LRU 512 条 —— 同一句话重复检索不必重复付费。 TokenUsageStatsServiceImpl:给运维台做只读聚合(按场景/模型/日趋势/成本)。

用量熔断(AiUsageGuard) ​

site.ai.daily-token-limit(0=不限)只统计门户侧(avatar_portal 前缀)token, 不把内部任务(日报/记忆抽取/向量化)算进去 —— 否则内部任务会把访客额度顶穿。 超限后:

  • 模式 off:不拦;alert:只发一次告警邮件;block:拒绝访客 AI 调用;
  • 告警每天最多一封,避免刷屏;
  • breaker-mode 写脏值会在保存侧被拒绝(见 6.2);读侧未知值按 block(安全默认)。

知识库向量块 ​

ai_kb_chunk 存文档分块与向量引用:KnowledgeBaseServiceImpl 负责导入/分段/向量化, KbChunkService 负责按知识库/文档检索。向量本身在 Hindsight/向量端口,MySQL 只存块与映射, OrphanVectorSweepJob 与 VectorGcJob 负责清理孤儿/过期向量。

3.7 module_ai:分身、对话、写作、知识库与每日总结 ​

模块卡 ​

项内容
一句话AI 产品层:对话、数字分身、写作助手、知识库/RAG 与每日总结。
用户功能后台 AI 对话(经 DSH)、门户数字分身、写作润色/扩写/翻译、知识库导入与问答、每日日记与文章草稿。
关键设计① 访客分身走 SQL 层 publicOnly 过滤,私有内容进不了上下文;② 长任务异步 + 显式状态机(processing/draft/ignored/failed),失败冷却重试;③ 发布后的 AI 增强失败不影响发布本身。
职责数字分身(门户访客版 + 博主版)、多会话 AI 对话(SSE)、写作助手、知识库/RAG、每日总结(日记)、发布后 AI 处理
入口/api/admin/ai(59 端点)、/api/portal/ai(访客分身)、MCP 无关(AI 能力多由扩展调用)
数据表ai_conversation、ai_message、ai_chat_turn、ai_knowledge_base、ai_kb_document、ai_daily_digest、ai_diary_revision、ai_digest_cursor(+ ai_prompt_history)
实现细节(点开:类、状态机、表结构、失败边界)
项内容
关键类AiChatServiceImpl、AiChatTurnService、AiAvatarServiceImpl、AiWritingServiceImpl、KnowledgeBaseServiceImpl、RagServiceImpl、DailyDigestJob/ServiceImpl、AdminChatDshClient
失败形态模型超时/限流;分身每日额度;总结失败进冷却重试;空输入记 ignored

对话:会话、上下文与流式 ​

  • 数据模型:ai_conversation(会话,带 scene 区分后台/分身)→ ai_message(消息)→ ai_chat_turn(一次问答的轮次与 token/耗时/状态,便于统计与重放)。
  • 上下文装配:系统提示词 = 站点人设 + 场景指令 + 记忆/知识检索片段(可配场景开关); 长对话按 token 预算裁剪,保留最近 N 轮 + 摘要。
  • 流式:/stream 用 SseEmitter,前端 fetch+ReadableStream 逐段渲染;出错时发 error 事件并落库失败状态。
  • 标题:首轮结束后异步生成会话标题(短、可重命名)。
  • 后台对话走 DSH:后台 AI 对话(admin-chat)不是直连模型,而是通过微信桥调度 DSH 会话 (AdminChatDshClient),桥把"超时但仍在执行"的回复登记为 pending,后端 AdminChatPendingJob 每 10 秒取回并落库;附件会物化到 DSH 工作目录,失败则回滚附件。

数字分身(两种可见性、同一套组件) ​

版本数据来源约束
门户访客版 /api/portal/ai/avatar公开知识库 + 公开文章摘要(publicOnly=true,SQL 层过滤)每日额度(site.ai.avatar.daily-limit,按访客 ID 限流)、敏感词/审核、免责声明、不读私有记忆
博主版(后台)私有记忆 + 笔记/日程(按隐私档)仍需出网台账;不对外

分身的"记忆"来自 RagService:访客版检索 SQL 强制 is_public=1,即使上层疏漏, 私有笔记也进不了上下文(这是数据层防线,不依赖调用方自觉)。

写作助手 ​

/api/admin/ai/writing:润色、扩写、缩写、摘要、续写、翻译、标题生成。 场景化提示词存 ai_prompt_template(可后台编辑,支持 {变量} 占位), 输入长度与输出长度都有限制;结果只进编辑器,不自动发布。

知识库与 RAG ​

  • 知识库 ai_knowledge_base(名称/描述/是否公开/来源过滤)→ 文档 ai_kb_document (标题/来源/Markdown/状态)→ 分块 ai_kb_chunk(序号/内容/向量引用)。
  • 导入:手动粘贴 / 文章导入 / 笔记导入;分段按标题与长度切分;向量化走网关 embed (失败重试,状态可见)。
  • 检索:RagService 按知识库范围 + 是否公开过滤,返回片段与来源;KbSourceFilter 决定哪些内容可以进哪个分身。

每日总结(日记):时间点轮询 + 状态机 ​

DailyDigestJob 每 60 秒轮询(fixedDelay),不解析 cron:读 site.ai.digest.time (默认 00:20),到点且"今天还没记录"就提交异步生成(aiExecutor,避免长 AI 调用占用调度线程)。 重启补偿:还没到今天的点、且"昨天"完全没有记录时补跑昨天(只补缺失,不重试失败)。

ai_daily_digest 状态机:

(无) ──claim──> processing ──成功──> note_only(只写日记) 
                    │                     └─ 配置开启 → draft(同时建文章草稿)
                    ├─ 无输入 ──> ignored(不调模型,止住每分钟重试)
                    └─ 异常 ──> failed(记录 error;10 分钟冷却后定时重试)

关键实现:

  • 幂等:date 唯一键 + 行级 claim(processing 抢占),重复触发不会生成两份;
  • 输入:当天对话轮次、待办完成情况、说说、课程、生活事件;备注等私密字段不进提示词;
  • 输出:summary_md(给人看的总结)与 diary_md(第一人称日记);日记可选参考 Hindsight 长期背景(site.ai.digest.hindsight-context.enabled);
  • 人工编辑:后台可改日记(ai_diary_revision 存版本历史),可重新生成/回填最近 7 天;
  • 失败不阻塞:异常收敛为 failed 记录,定时任务冷却重试,不会每分钟轰炸模型。

发布后 AI 处理 ​

ArticlePublishAiListener 监听发布事件(AFTER_COMMIT),异步做三件事: 生成摘要、推荐标签、向量化入库(知识库/RAG 可用)。任一失败只记日志,不影响文章已发布的事实 ——AI 是增强,不是发布的前置条件。

失败与边界 ​

  • 模型超时(默认 120s)与限流:错误如实返回;流式连接中断由客户端重连;
  • 分身额度用尽:明确提示"今天的会话数已达上限";
  • 每日总结:无输入记 ignored(省成本)、失败进冷却重试、人工可重生成;
  • 发布后 AI 处理失败不回滚发布;
  • 后台对话 DSH 超时:转 pending 由 Job 异步取回,用户不会"等到天荒地老"。

3.8 module_agent:AI 助理的工具面(MCP)与人设 ​

模块卡 ​

项内容
一句话把博客能力做成 AI 可调用的 MCP 工具面,并管理人设、模型与令牌。
用户功能微信/DSH 通过工具查日程、写记忆、建提醒、写草稿、记生活事件;后台配置人设、模型、权限与令牌;生成 instructions。
关键设计① 主 MCP 30 工具 + 扩展 MCP 40 工具,按 scope 校验;② 写工具回读校验后才说成功,更新 0 行必须如实报告;③ instructions 按预算裁剪,且生成时也记出网台账。
职责把博客/日程/记忆能力暴露成 DSH 可调用的 MCP 工具;生成 instructions;人设与对话模型;令牌与 scope;后台对话 DSH 调度
入口POST /api/agent/mcp(主 MCP,30 工具)、POST /api/agent/extensions/mcp(扩展 MCP,40 工具)、GET /api/agent/instructions.md
数据表agent_token、ai_prompt_history(+ 人设档案 PersonaSnapshot 存 Hindsight;旧 ai_profile 表已删;DSH session 文件)
实现细节(点开:类、状态机、表结构、失败边界)
项内容
关键类McpToolServiceImpl、McpToolProvider 接口 + 9 个 provider、AgentInstructionsService、AssistantProfileServiceImpl、AdminChatDshClient、AgentAuthInterceptor
失败形态无权限 403;未知工具/参数错误明确返回;写工具"回读校验"后才能说成功

MCP 协议端点 ​

McpController 实现 JSON-RPC 2.0 over HTTP(streamable-http):initialize、tools/list、 tools/call。鉴权由 AgentAuthInterceptor 完成:Bearer 专用令牌(600 权限文件)

  • scope(memory:write/daily:write/mcp/ext 等)+ IP 白名单 + 限速; 每次调用写 agent_tool_call_log(工具名、参数摘要、结果字节、耗时、caller)。

工具面分层:McpToolServiceImpl 只做协议与分发;具体工具按领域拆成 provider:

Provider工具(示例)说明
DailyToolProviderdaily_brief、daily_todo(含步骤/系列)、daily_course、remind、schedule_fix只通过 module_daily 的 Service 读写
MemoryToolProvidermemory_search/write/fact_upsert/forget/verify、emotion_note、care_reply、open_loop、disagreement、ritual、procedure、narrative、profile_update13 个工具,关系层与记忆层的入口
LifeToolProviderevent_record、event_query、plan_deviation、image_ingest、coverage生活数据管道;聚合在 SQL 层
ContentToolProviderarticle_draft_create、talk_publish、相册类写内容只到草稿;发布权在人
SearchToolProviderkb_search、session_search原文检索(文章/笔记/说说;历史会话原话)
AlbumToolProvideralbum_photo相册:收照片/查相册(从微信桥工作区取图)
OpsToolProviderjob_run、job_status后台任务投递与查询
ReflectToolProviderreflectHindsight 多轮推理
ExtensionToolProviderextension_*(40 个)扩展平台的开发/安装/运行工具面

工具实现的四条纪律(所有 provider 共享):

  1. 权限先判:读工具要读 scope,写工具要写 scope;缺 scope 返回 403 并说明缺哪个。
  2. 参数必校验:缺必填/格式错要在工具层给出可执行提示(如"when 必须是绝对时间 YYYY-MM-DD HH:mm,先把'下周三'算出来"),不能把参数问题说成"存储坏了"。
  3. 回读校验:写成功后回查一次(id 存在/状态已变),verified 才说成功; 更新 0 行要如实说"没找到/没生效",不能假称成功(审查 #80/#81/#84 都是这类)。
  4. 回执给下一步:成功给"接下来会发生什么",失败给"怎么改参数"; 跳过给理由(skipped 而不是空字符串)。

主 30 工具清单见附录 K;扩展 40 工具由扩展包 manifest 声明、ExtensionMcpController 动态暴露(能力目录附录 N)。

instructions:给模型"人设 + 事实 + 边界"的提示词 ​

GET /api/agent/instructions.md 由 AgentInstructionsService 生成,供微信桥每轮拉取 (桥会按时间头刷新)。内容分节:人设(来自 PersonaSnapshot / Hindsight directive;旧 ai_profile 表已删)、当前关系阶段/直言度、 今日日程摘要、未了线头、分歧、程序/仪式、记忆使用规则、工具使用规则、隐私红线。 生成时:

  • 按 token/字数预算裁剪各节(超长节做摘要),避免提示词无限膨胀;
  • 读取的私密内容不进入公开场景;
  • 生成动作本身也记出网台账(上下文注入了哪些内容)。

人设与对话模型 ​

  • PersonaSnapshot(人设档案,v18 起存 Hindsight directive;旧 ai_profile 表已删):昵称、作息、语气、兴趣、禁区、关系阶段、直言度。 助手可通过 profile_update 局部更新(只改传入字段,不会把没传的字段清空); 关系阶段/直言度是"本人定义",工具不给入口,只能建议。
  • 模型配置:当前 provider/model/reasoningEffort 存在 DSH profile 的 patch 文件里; 后台可读可改(写前备份,改后验证),由 AssistantProfileServiceImpl 与 AssistantPermissionService 管理权限与路径。
  • 令牌:agent_token 只存前缀与哈希,明文只在创建时返回一次;可启停、删除、看最后使用时间。

后台 AI 对话:借道 DSH ​

后台"AI 对话"不是直连模型,而是:

后台 → AdminChatDshClient → 微信桥 /admin-chat → DSH 会话
                                    │ 超时未答的 turn 登记 pending
                                    ▼
                     AdminChatPendingJob(每 10s)→ 取回 → 落库 → 前端轮询可见

附件先由 ChatAttachmentService 存到私有目录,再物化到 DSH 工作目录(chat-cache)供其读取; 物化失败回滚附件记录,避免"上传成功但模型看不到"。

失败与边界 ​

  • 令牌无效/scope 不足:401/403 且给出缺哪个 scope;
  • 工具参数错:isError=true + 可执行提示;未知名/未知 action 明确拒绝;
  • 写工具回读失败:如实报"没存上",绝不假成功;
  • DSH 挂起/超时:后台对话转 pending 异步取回,不会无限等待;微信桥侧超时先回"还在做"。

3.9 module_conversation:DSH 会话采集、回看与附件 ​

模块卡 ​

项内容
一句话所有通知的唯一出口:微信 → 邮件 → 站内。
用户功能晨报/提醒/告警的送达;失败自动重试并回写业务;主动消息预算与反馈台账。
关键设计① 先插 pending 抢唯一键,天然防重复;② sent 只在通道自报成功时写(2xx 但业务失败不算);③ 站内兜底不掩盖外部失败,否则重试机制失效。
一句话把 DSH 会话可靠地收进来、看得到,并把聊天附件安全地管起来。
用户功能后台按会话回看对话与工具调用;聊天附件上传/下载;采集水位与心跳;原话检索。
关键设计① 摄取先落 RAW 再解析(解析失败不丢数据);② 水位在服务端原子推进,失败不推进;③ 附件私有目录 + 归属校验 + nosniff,后台对话再物化给 DSH。
职责采集 DSH 会话(增量、水位、幂等)、后台回看与检索、工具调用审计、聊天附件私有存储
入口POST /api/agent/ingest/session(宿主采集脚本调用)、/api/admin/agent、/api/admin/chat/attachments
数据表agent_session、agent_turn、agent_session_raw、agent_ingest_log、agent_tool_call_log、agent_turn_attachment、chat_attachment
实现细节(点开:类、状态机、表结构、失败边界)
项内容
关键类AgentIngestServiceImpl、AgentSessionQueryServiceImpl、ChatAttachmentServiceImpl、RawRetentionJob、LedgerRetentionJob、AdminChatPendingJob(在 module_ai)
失败形态摄取先落 RAW 再解析(解析失败不丢数据);水位在服务端,失败不推进

会话摄取:水位 + 幂等 + 降级 ​

宿主 collect-sessions.sh 每 5 分钟读 ~/.dsh/sessions 的增量行,POST 到 /api/agent/ingest/session:

  1. 鉴权:采集令牌(agent:ingest scope)+ IP 白名单 + 限速;
  2. RAW 先落库:原始行进 agent_session_raw(去重键 session_id + line_no), 解析失败也不丢原文;
  3. 解析降级:能解析的写 agent_session/agent_turn(用户/助手/工具调用), 不能解析的保留 RAW 并计数;
  4. 水位:agent_ingest_log.last_line_no 由服务端原子推进;客户端只有确认水位推进才继续下一批。 好处:断点续采、重启不重复、不丢消息。
  5. 心跳:摄取成功顺带上报 heartbeat,让"采集器还活着"可查。

DSH 会话只采微信与后台(cwd_slug 白名单/排除项),代码/终端会话不采,避免噪音与隐私。

回看与检索 ​

  • 后台会话列表(不含逐行正文,只看标题/轮数/时间),点进去按页取 turns;
  • SessionSearchService 给 MCP session_search 提供"原话检索"(按关键词,带上下文窗口);
  • AgentToolCallAuditService 记录 DSH 调用的工具名/参数摘要/结果字节(不含正文);
  • 附件在 turn 上以 agent_turn_attachment 关联。

聊天附件:私有存储 + 归属校验 + 物化 ​

ChatAttachmentServiceImpl:

  1. 校验类型(第一期只接图片;扩展名 + 魔数)、大小上限;
  2. 计算 sha256,按 年/月/sha256.ext 存到私有目录(COSMOS_CHAT_ATTACHMENT_DIR, 生产 /opt/vite-cosmos/uploads/chat-files);
  3. 写 chat_attachment(owner_type/owner_id、mime、size、storage_key、status);
  4. 下载必须带归属会话(owner_id)校验,响应头强制 nosniff + inline;
  5. 后台对话场景再物化到 DSH 工作目录;失败回滚记录与文件。

历史附件曾写在镜像内目录(随镜像更新丢失)—— deploy/scripts/migrate-chat-attachments.sh 已把旧目录迁到挂载卷;早期丢失的 1 个文件不可恢复,已在审查记录中标注。

保留策略 ​

  • RawRetentionJob:agent_session_raw 按天清理(默认 14 天,可配);
  • LedgerRetentionJob:agent_tool_call_log + ai_egress_log 按保留期(默认 180 天)分批清理, 删除 0 行也写日志;
  • agent_turn 保留默认永久(可配开关),审查记录里把它列为"积压可选清理"。

3.10 module_notify:通知投递与主动性预算 ​

模块卡 ​

项内容
一句话运维台:健康、清理、导入导出、版本回滚与 AI 能力看板。
用户功能综合健康/数据库/日志查看;磁盘与日志清理;外链巡检;DSH 版本与回滚;Markdown/WordPress 导入;AI 域导出。
关键设计① 清理前做引用反查,反查失败保守保留;② 导入默认草稿 + HTML 转义,绝不自动发布;③ 能力健康用「开关 + 产出物 + 日志」三看判据,避免把没运行当成健康。
职责多通道通知投递(webhook→email→inapp 降级)、失败重试与业务回写、主动性账本与预算
入口内部 SPI(NotifyService);无 HTTP 控制器(由扩展 effect 与业务调用)
数据表notify_channel、notify_log、webhook_delivery、proactive_log
实现细节(点开:类、状态机、表结构、失败边界)
项内容
关键类NotifyServiceImpl、WebhookNotifySender、EmailNotifySender、InappNotifySender、NotifyRetryJob、ProactiveBudgetServiceImpl
失败形态幂等抢占防重复;sent 只在通道自报成功时写;全失败记 failed 交给重试

投递模型(无 MQ 的现实约束) ​

  1. 幂等抢占:先插 notify_log(status=pending),dedup_key 唯一索引兜底; 冲突即"同一条已投过",直接返回(宁可拒发也不重复轰炸)。
  2. 降级链:按 notify_channel.priority(小=优先)尝试可用通道: 微信(桥 webhook)→ 邮件(SMTP)→ 站内(inapp)。成功即 sent 并记录实际通道。
  3. 成功判据:通道自报成功才算 sent —— HTTP 2xx 且应答体没有业务错误码 (WebhookNotifySender.detectBizError);否则记 failed,交 NotifyRetryJob。
  4. 站内兜底:没有任何可用外部通道时降级 inapp;但"有通道却发失败"仍记 failed, 兜底不掩盖外部失败。
  5. 重试:失败按 retry<2 重投;重投成功通过 NotifyRetryLinkHandler 回写业务表 (如提醒状态),避免"用户已收到、业务仍显示失败,再点重试又发一条"。
  6. 微信桥的附加保障:桥侧 /notify 有 24 小时去重、发送重试 3 次、失败入待送队列, 并在 /health 暴露最近一次发送结果。

主动性预算账本 ​

proactive_log 记录每条主动消息(晨报/晚报/关怀/线头/周复盘…)的去重键、结果、反馈。 ProactiveBudgetServiceImpl 提供幂等写入、日/月计数与反馈统计;真正的限额判定在扩展 handler 的 ProactiveSwitch/预算能力里(见 4.5),账本只负责"记过什么"。

3.11 module_ops:运维台、导入导出与 AI 看板 ​

模块卡 ​

项内容
职责健康自查、数据库观测、磁盘清理、版本/回滚、外链巡检、任务与审计日志、内容导入、AI 域导出、能力健康看板
入口/api/admin/system/ops(27 端点)、/api/admin/system/import、/api/admin/system/export、/api/admin/ops
数据表不拥有业务表(只读跨模块 + 系统日志表)
实现细节(点开:类、状态机、表结构、失败边界)
项内容
关键类OpsServiceImpl、CapabilityHealthService、AiOpsConsoleServiceImpl、ContentImportServiceImpl、AiDataExportServiceImpl、DashboardServiceImpl
失败形态清理有保底与引用反查;导入默认草稿;未知清理目标明确报错

健康与观测 ​

  • /ops/health-report:DB 版本/连接、磁盘、Hindsight、桥、最近任务、备份新鲜度;
  • /ops/db-info:表行数与体积(只读);
  • /ops/logs:日志尾部(默认 200 行,限长);
  • /ops/jobs:sys_job_log 分页;/ops/jobs/{name}/run 白名单触发任务;
  • /ops/link-check:外链可用性巡检(并发 + 超时);
  • /ops/version、/ops/rollback/status:版本与回滚就绪状态;
  • /ops/cleanup:按目标清理 —— 孤儿文件(引用反查 fail-safe)、过期日志、过期备份、 审计/搜索/邮件/任务/访客日志(保留天数参数)。未知目标返回"未知清理目标",不静默成功;
  • doctor.sh(宿主脚本)覆盖端口/挂载/令牌/备份/迁移/环回绑定等 25 项,发布后必跑。

AI 运维看板 ​

CapabilityHealthService 用三看判据(开关 + 产出物时间戳 + 任务日志)给每个能力打状态: 只看任务日志不成立(多个 Job 在"开关关着/本周期已有产出/上一轮未结束"时故意不写日志); "判据为空 ≠ 通过"这条纪律就落在这里。AiOpsConsoleService 汇总用量/成本/预算/发现的问题 (findings:全局断网、最近一次 skipped、上游静默),全部只读。

内容导入(两个格式) ​

ContentImportServiceImpl:

格式支持关键点
Markdown ZIPHexo/Leanote/Obsidian 等导出的 .md 集合(front-matter)单次 ≤500 篇、单篇 ≤2MB、ZIP ≤50MB;默认草稿;HTML 转义防 XSS;skipExisting 按标题幂等;识别导出包布局:有 articles/ 前缀时只导入该目录,notes/、README 等计为跳过(审查 #82)
WordPress WXRcontent:encoded + wp:post_type=postXML 解析限总量;HTML→Markdown 轻量转换(标题/段落/列表/链接/图片/代码/强调);XSS 转义

导入动作统一走 ArticleService.save,因此与手工发文一样有渲染、摘要、事件。

数据导出(带走自己的数据) ​

AiDataExportService/ExportAdminController:

  • JSON:记忆、线头、洞察、画像、每日总结、课程/待办/提醒(程序可读);
  • Markdown ZIP:文章(front-matter + 正文)、笔记、README;供备份/迁移;
  • CSV/表格:用量等统计;
  • 导出是只读动作,审计留痕由控制器负责。

失败与边界 ​

  • 清理:引用反查失败按"未知"保留;保留期可配;备份清理保留最新可恢复点;
  • 导入:部分失败不阻塞其它文档,结果逐条说明;默认草稿,绝不自动发布;
  • 看板:只读,不写业务表;能力健康判据在文档与响应里都解释清楚,避免"数字看起来正常"。

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